Authentication & authorization

For API v2, OAuth2 is used as an authentication and authorization framework. In short, every API request needs an Authorization header carrying your OAuth2 access token. We will explain how it looks like and what the possibilities are.

Key features

• OAuth2 is used for authentication and authorization
• Every API request needs an Authorization header

You need this to succeed

This is what you need to use the Showpad REST API:

• Showpad’s Ultimate pricing plan
• Access to Showpad Online Platform
• Basic Knowledge of REST
• Basic Knowledge of JSON

The quick way to awesomeness

• API Key Header
• OAuth Clients
• Client Scopes
• Server-side flow
• The identity of the user requesting authorization is verified
• The client authorization is verified
• Verify the client's identity
• Access Token response
• Refresh Token Flow
• User Credentials Flow
• Access Token response

API Key Header

Obtaining an access token can be done using the Server-Side flow, the Refresh Token flow or the User Credentials flow. Each flow is discussed in detail in a later section of this document.

Authorization: Bearer myOAuth2AccessToken

OAuth Clients

In OAuth2, every application that connects with the Showpad API is defined as a client. Each client has to be registered on Showpad in order to provide a level of trust. An important parameter of the client is its callback URL. This URL is used when obtaining an access token, but also forms a way of authenticating the client. 

You can register an OAuth2 client via the API section which can be found in the Admin Settings of your Showpad account.

1. Choose Manage OAuth Clients.
   
2. Click + to add an OAuth2 Client.
   
3. Enter your client details, define the scope (for more info, see "Client Scopes" below), and click Add.

Client Scopes

Each client is also characterized by its scopes. A scope is a set of client permissions that allow access to certain resources. For example, the read_user_management scope gives the client access to read (and only read) user data. The table below lists all scopes.  

When talking about scopes, it's important to realize that each user has to authorize the client for being allowed these scopes. This is further illustrated in the authentication flow below. When a client changes its scopes, all authorizations and access tokens are revoked, forcing each user to reauthorize their client on API access. 

Server-side flow

The client application contacts the Showpad's Authorize endpoint. The endpoint should be accessed via GET https://my-subdomain.showpad.biz/api/v2/oauth2/authorize. There are 3 query parameters needed and they should be sent as Url parameters:

The identity of the user requesting authorization is verified

1. If the user is already logged in, the user is redirected to the client authorization part (step 3).
2. If the user is not logged in, he will be asked to enter his credentials. The user will be redirected to https://my-subdomain.showpad.biz/login.
3. Once his credentials have been entered, Showpad verifies the identity.
4. Once the identity has been verified, the client can be authorized (step 3).

The client authorization is verified

1. If the client was already authorized by the user in the past, a temporary authorization code will be created and returned to the client via step 4.
2. If the client was not already verified by the user, the user will be forwarded to a client authorization page. Here, the user will be able to view a description of the client he is connecting with. He will also have to agree with the set of scopes required by the client.
3. If the client agrees with the client's requirements, a temporary authorization code is generated. 
4. If the client does not agree with the client's requirements, the authorization process cannot continue.
5. The user will be redirected to the redirect URL as specified in step 1. It will contain 2 query parameters.

The client application requests an access token via POST https://my-subdomain.showpad.biz/api/v2/oauth2/token. The following parameters should be added as part of the POST body. The request should be authenticated with HTTP Basic using the client ID and client secret.

Verify the client's identity

1. If the client passed the correct ID and secret via HTTP basic, the authorization code and callback URL are verified as shown in step 7.
2. If the client passed an incorrect ID and secret combination, the authentication flow stops. 

Verify the authorization code and callback URL. The code is only valid for 30 seconds so be sure to exchange the authorization code for an access token as quickly as possible in step 5.

1. If the authorization code and callback URL are valid, an access and refresh token are created in step 8.
2. If the authorization code and/or the callback URL are invalid, the authentication flow stops.

The access and refresh tokens are sent back to the client. Below is an example of such a response.

Access Token response

{ 
"access_token":"3eb33bef34d208479d5ee291307c330864b40e87",
"expires_in":3600,
"token_type":"Bearer",
"scope":"refresh_token read_user_management write_user_management 
read_contentprofile_management write_contentprofile_management 
read_division_management write_division_management",
"refresh_token":"7196116f9a1d56411b8fe621d4afda9b9eb4ae93"
}

The client can now access the Showpad API. It suffices to add the access token to the Authorization header in the form: Bearer myAccessToken

The Showpad Service will respond with

• a 401 if your access token is invalid.
• a 403 if your access token is valid, but you do not have access to the requested resource.

Refresh Token Flow

An access token will typically expire an hour after it was obtained. When an access token has expired, you can obtain a new access token via the refresh token flow. After refreshing the access token, you will receive a new access and refresh token. 

The following steps are needed to refresh an access token.
The client application requests an access token via POST https://my-subdomain.showpad.biz/api/v2/oauth2/token . The following parameters should be added as part of the POST body. The request should be authenticated with HTTP Basic using the client ID as the username and client secret as the password.

The access and refresh tokens are sent back to the client. Below is an example of such a response.

Access Token response

{ 
"access_token":"3eb33bef34d208479d5ee291307c330864b40e87",
"expires_in":3600,
"token_type":"Bearer",
"scope":"refresh_token read_user_management write_user_management 
read_contentprofile_management write_contentprofile_management 
read_division_management write_division_management",
"refresh_token":"7196116f9a1d56411b8fe621d4afda9b9eb4ae93"
}

Note: A refresh token is typically valid for 14 days. After 14 days, you need to repeat the Authentication Flow to obtain an access token. 

User Credentials Flow

Showpad also provides a way to get an access and refresh token by using the user's username and password. This flow is called the User (Resource Owner) Credentials Flow and is typically used in cases where there is a strong level of trust between the client and the user.

The following steps are needed to obtain an access token:

The client application requests an access token via POST https://my-subdomain.showpad.biz/api/v2/oauth2/token. The following parameters should be added as part of the POST body. The request should be authenticated with HTTP Basic using the client ID as the username and client secret as the password.

The access and refresh tokens are sent back to the client. Below is an example of such a response.

Access Token response

{ 
"access_token":"3eb33bef34d208479d5ee291307c330864b40e87"
"expires_in":3600,
"token_type":"Bearer"
"scope":"refresh_token read_user_management write_user_management 
read_contentprofile_management write_contentprofile_management 
read_division_management write_division_management"
"refresh_token":"7196116f9a1d56411b8fe621d4afda9b9eb4ae93"
}