OAuth2 is used as an authentication and authorization framework for the API. 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
- Create personal tokens to authenticate with a token instead of a password
- TTL for the token is 14 days by default, with a maximum of 90 days
- 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
- API Key Header
- OAuth Clients
- Personal tokens
- 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
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 |
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.
- Choose Manage OAuth Clients.
- Click + to add an OAuth2 Client.
- Enter your client details, define the scope (for more info, see "Client Scopes" below), and click Add.
- You can change the default TTL of the token to 90 days. By default, the setting is set to 14 days.
Personal access tokens allow you to authenticate with the Showpad API instead if using a password.
From the API settings on the Online Platform, you can name your token and give it an expiry date.
- Go to the API tab in the Admin Settings.
- Give your token a name and set an expiry date.
- Copy the token and use it in your application. This token is only displayed once and you can't retrieve it later. Store it in a safe location for future usage. Click Done.
- To revoke access, click Revoke.
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.
Scope | Description |
---|---|
refresh_token | Refresh access token using a refresh token |
read_user_management | Read user data (includes users, usergroups and user permissions) |
write_user_management | Write user data (includes users, usergroups and user permissions) |
read_contentprofile_management |
Read content profile related resources (content profiles, assets, tags, tickets and comments) |
write_contentprofile_management | Write content profile related resources (content profiles, assets, tags, tickets and comments) |
read_division_management | Read division related resources (divisions and division permissions) |
write_division_management | Write division related resources (divisions and division permissions) |
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.
The client application contacts the Showpad's Authorize endpoint. The endpoint should be accessed via GET https://my-subdomain.showpad.biz/api/v3/oauth2/authorize. There are 3 query parameters needed and they should be sent as Url parameters:Click here to open the diagram in a separate window.
Parameter | Required | Description |
---|---|---|
client_id | yes | The ID of your OAuth2 client as obtained from the online platform. |
redirect_uri | yes | The callback URL, called after a successful authorization request. This URL should be specified when registering the OAuth2 client. |
response_type | yes | This should be "code" for this authentication flow |
state | no | Additional URL-encoded data that will be returned via the callback URL |
scope | no | Specify which scopes this request should be limited to. You cannot specify a scope the client is not authorized to use. For more information, see Client Scopes |
The identity of the user requesting authorization is verified
Click here to open the explaining diagram in a separate window.
- If the user is already logged in, the user is redirected to the client authorization part (step 3).
- 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.
- Once his credentials have been entered, Showpad verifies the identity.
- Once the identity has been verified, the client can be authorized (step 3).
The client authorization is verified
Click here to open the explaining diagram in a separate window.
- 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.
- 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.
- If the client agrees with the client's requirements, a temporary authorization code is generated.
- If the client does not agree with the client's requirements, the authorization process cannot continue.
- The user will be redirected to the redirect URL as specified in step 1. It will contain 2 query parameters.
Parameter | Description |
---|---|
code | The authorization code which should be used in step 5. This 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. |
state | The state that was sent as a parameter in step 1 |
The client application requests an access token via POST https://my-subdomain.showpad.biz/api/v3/oauth2/token. The following parameters should be added as part of the POST body.
Parameter | Required | Description |
---|---|---|
grant_type | yes | This should be authorization_code for this authentication flow |
code | yes | The authorization code as retrieved in step 4 |
redirect_uri | yes | The callback URL as used in step 1 and specified when the OAuth2 client was registered |
state | no | Additional url-encoded data that will be returned |
Click here to open the explaining diagram in a separate window.
- 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.
- 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.
- If the authorization code and callback URL are valid, an access and refresh token are created in step 8.
- 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":"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" } |
Parameter | Description |
---|---|
access_token | The access token that will grant you access to protected resources. Add it to the request via the Authorization header in the form: Bearer myAccessToken |
expires_in | The number of seconds after which the access token will expire (1 hour or 3600 seconds by default) |
token_type | Bearer |
scope | A space delimited collection of scopes this access token can be used for |
refresh_token | This token can be used to obtain a new access token (e.g. when the token has expired). This refresh token is only valid once and will be replaced when a new access token is obtained. |
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.
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/v3/oauth2/token . The following parameters should be added as part of the POST body.
Parameter | Required | Description |
---|---|---|
grant_type | yes | This should be refresh_token for this authentication flow |
refresh_token | yes | The refresh token obtained from the Authentication Flow request (step 8) |
state | no | Additional URL-encoded data that will be returned |
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.
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/v3/oauth2/token. The following parameters should be added as part of the POST body.
Parameter | Required | Description |
grant_type | yes | This should be "password" for this authentication flow |
username | yes | The username of the user you want to obtain an access token for |
password | yes | The password of the user you want to obtain an access token for |
state | no | Additional URL-encoded data that will be returned |
client_id | yes | Parameters can be found in the OP after creating the OAuth client |
client_secret | yes | Parameters can be found in the OP after creating the OAuth client |
The access and refresh tokens are sent back to the client. Below is an example of such a 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" } |