Authentication
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
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.
- 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 Tokens
Personal access tokens allow you to authenticate with the Showpad API instead of using a password.
From the API settings on the Online Platform (OP), 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 cannot retrieve it later.
- Store it in a safe location for future usage. Click Done.
note
You may revoke token access by clicking Revoke.
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.
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 is 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://{subdomain}.showpad.biz/api/v3/oauth2/authorize
. There are three (3) required query parameters needed
(i.e., client_id
, redirect_uri
, and response_type
) that must be sent as URL parameters.
Check the following table below for the complete list of query parameters available:
Parameter | Required | Description |
---|---|---|
client_id | yes | The ID of your OAuth2 client as obtained from the Online Platform. |
redirect_uri | yes | The callback URL which is called after a successful authorization request. This URL should be specified when registering the OAuth2 client. |
response_type | yes | This should be the code for this authentication flow. |
state | no | Additional URL-encoded data that will be returned via the callback URL. |
scope | no | Specifies 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. |
To better visualize the authentication flow, check out the flow diagram provided below:
The identity of the user requesting authorization is verified
- 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://{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). Back to the menu
The client authorization is verified
- 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://{subdomain}.showpad.biz/api/v3/oauth2/token
. The
following parameters should be added as part of the POST
body.
Parameter | Required | Description |
---|---|---|
client_id | yes | The ID of your OAuth2 client as obtained from the Online Platform. |
client_secret | yes | Parameters can be found in the OP after creating the OAuth client |
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 |
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://{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 |
client_id | yes | The ID of your OAuth2 client as obtained from the Online Platform. |
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"
}
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://{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"
}