Authentication

Showpad API uses OAuth2 as the authentication and authorization framework. OAuth is a standard that works over HTTPS to authorize and provide with "secure delegated access" to devices, APIs, servers, and applications with access tokens rather than credentials.

Prerequisites

• Ultimate subscription to Showpad
• Administrator access to Showpad's Online Platform

Personal API Tokens

Personal API tokens allow you to authenticate with Showpad API instead of using a password. To get a personal API token, open the API menu in the Admin Settings of the Online Platform.

1. Click the API Tokens link.

2. In the API Tokens form, enter the following information:
   • Name - A descriptive name for the token.
   • Expiry date (optional) - The date of the token's expiration.

3. Click the Add button.

4. Copy the displayed token and store it in a safe location for future use. This token is only displayed once and you cannot retrieve it later.

4. Click the Done button.

Revoke Token

You can revoke a token by clicking the Revoke button.

OAuth Clients

Every application connecting with Showpad API must be registered as a client with a defined scope. The following sections describe how to register your OAuth client(s), as well as detailed explanations of each scope.

Registration

To register an OAuth2 client and define its scope, open the API menu in the Admin Settings of the Online Platform.

1. Click the Manage OAuth Clients link.

2. Click the + icon to add a new OAuth2 Client.

3. In the Edit OAuth Client form, enter your client details:
   • Name - A descriptive name to identify the client.
   • Redirect URL - The callback URL for the client application accessing Showpad.
   • Description - Text to describe the client and its purpose.
   • Website - A website for context purposes. It doesn't affect the functioning of the OAuth client.
   • Scope - Select the checkbox to indicate the client's scope.
   • Refresh Token Lifetime - Specify the length of the client's token.

4. When you've finished, click the Update button.

Your new OAuth client is added to the list of registered clients and automatically assigned a Client ID and Secret. This information is sent as parameters when accessing Showpad with an API Token.

Remove Registration

You can remove a client registration by selecting one from the list and clicking the Delete icon (trash can) in the right panel.

Scopes

Scopes are a set of permissions that define a client's level of access to certain resources. Each user must authorize the scopes for their clients. When a client scope is changed, all previous authorizations and access tokens are automatically revoked.

The table below describes the available scopes for your clients.

Checkbox	Scope	Description
Automatically refresh access tokens	refresh_token	Allows the refresh of access tokens.
View user releated resources	read_user_management	Allows read access for user data (includes users, usergroups and user permissions).
Edit user related resources	write_user_management	Allows write access for user data (includes users, usergroups and user permissions).
View content related resources	read_contentprofile_management	Allows read access for content profile-related resources (content profiles, assets, tags, tickets and comments).
Edit content related resources	write_contentprofile_management	Allows write access for content profile-related resources (content profiles, assets, tags, tickets and comments).
View division releated resourcres	read_division_management	Allows read access for division-related resources (divisions and division permissions).
Edit division related resources	write_division_management	Allows write accesss for division-related resources (divisions and division permissions).
AppsDB online integrations	appsdb_online_integrations	Enables usage of AppsDB without a Showpad App. Note: This feature requires activation. Please contact your Customer Success Manager if you're interested in using it.

OAuth Grant Types

An OAuth2 grant type is how an application gets an access token. Showpad has defined several grant types, each is optimized for a particular use case:

• Server-Side
• Refresh Token
• User Credentials

Each of these flows is designed to serve the most common use cases. The following sections describe each flow in detail.

Authorization Code Flow

In the authorization code flow, a client application contacts Showpad's Authorize endpoint:

GET https://{{subdomain}}.showpad.biz/api/v3/oauth2/authorize

This call initiates the following authorization process:

The initial call must include three required parameters. The following table describes the complete list of available query parameters:

Parameter	Required	Description
client_id	Yes	The ID assigned to your OAuth2 client during registration in the Online Platform.
redirect_uri	Yes	The callback URL specified when registering the OAuth2 client. This URL is called after a successful authorization request.
response_type	Yes	This should be code.
state	No	Additional URL-encoded data to be returned via the callback URL.
scope	No	Specifies the scope limitations of the request. You cannot specify a scope the client is not authorized to use.

Process Description

Step	Description
1 & 2	User verfication. If a user is: already logged in to Showpad, they are automatically redirected to step 3. not logged in, they will be redirected to https://{{subdomain}}.showpad.biz/login to enter their credentials.
3	Client authorization. If the client was: previously authorized in the past, a temporary authorization code will be created. not previously verified, the user will be forwarded to a client authorization page where they can view a description of the client and its scopes. With agreement - a temporary authorization code is generated. No agreement - the authorization process cannot continue.
4	Create authorization code. Once authorized, the user is then redirected to the redirect URL with the following parameters: Parameter Description code The authorization code to provide in exchange for an access token. This is only valid for 30 seconds, so be sure to make the exchange as quickly as possible. state The state that was sent as a parameter in the first step.
5	Request access token. The client application requests a token via POST https://{{subdomain}}.showpad.biz/api/v3/oauth2/token with the following parameters in the body: Parameter Required Description client_id Yes The ID of your OAuth2 client as obtained from the Online Platform. client_secret Yes Available in the Online Platform after creating the OAuth client. grant_type Yes Should be: authorization_code code Yes The authorization code provided in step 4. redirect_uri Yes The callback URL specified in the Online Platform 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. The refresh token flow allows you to obtain a new access token when the previous token has expired.

To refresh an access token, the client application sends a request:

POST https://{{subdomain}}.showpad.biz/api/v3/oauth2/token

The following parameters should be included in the request body:

Parameter	Required	Description
grant_type	Yes	Should be: refresh_token
refresh_token	Yes	The refresh token obtained during step 8 of the original authentication flow.
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	Available in the Online Platform after creating the OAuth client.

Showpad sends new access and refresh tokens back to the client.

Example

{
  "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 must repeat the process to obtain a new access token.

User Credentials Flow

Showpad also enables obtaining access and refresh token via username and password. This is typically used in cases where there is a strong level of trust between the client and the user.

The client application requests an access token via

POST https://{{subdomain}}.showpad.biz/api/v3/oauth2/token

The following parameters should be included in the request body:

Parameter	Required	Description
grant_type	Yes	Should be password
username	Yes	The user's username.
password	Yes	The password for the username.
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	Available in the Online Platform after creating the OAuth client.

Examples

curl --request POST \
   --url https://{{subdomain}}.showpad.biz/api/v3/oauth2/token \
   --header 'Content-Type: application/x-www-form-urlencoded' \
   --data-urlencode 'grant_type=password' \
   --data-urlencode 'username=johnqpublic' \
   --data-urlencode 'password=mystrongpassword' \
   --data-urlencode 'client_id=FRZXGQFNMILL1YUCX3HMF350WM3ZRYTLXEBNMNIFHNU5S6WZJDOBG' \
   --data-urlencode 'client_secret=e75i3nhgclzcf5hrspah1wpak5efut1kj45b9mxl'

Showpad sends new access and refresh tokens back to the client.

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

Using API Tokens

Once you've retrieved an API token, it should be used in the header of every API request:

curl --request GET \
  --url https://{{subdomain}}.api.showpad.com/v4/users \
  --header 'Authorization: Bearer <myAPItoken>' \
  --header 'Content-Type: application/json'