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.

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.
   • Showpad side:
     • Name: We recommend a suitable name for the OAuth client so it's easy to find.
     • Redirect URL: The callback URL.
     • Description: Provide a summary of the integration.
     • Website: This is for context purposes only and doesn't affect the functioning of the OAuth client.
     • Your preferred refresh and lifetime options.
   • Client side:
     • Showpad URL: Your Showpad domain (https://OrganizationName.showpad.biz)
     • Client ID: Generated after completing the form in Showpad.
     • Client Secret: Generated after completing the form in Showpad.
4. 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.

1. Go to the API tab in the Admin Settings.
2. Give your token a name and set an expiry date.
3. Copy the token and use it in your application. This token is only displayed once and you cannot retrieve it later.
4. 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

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://{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). Back to the menu

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.

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"
}