Skip to main content

Authentication

Showpad APIs use 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.

Personal API Tokens

Personal API tokens allow you to authenticate with Showpad APIs 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.

Personal API Token

  1. 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.

Personal API Token

  1. Click the Add button.

  2. 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.

Personal API Token

  1. Click the Done button.
Revoke Token

You can revoke a token by clicking the Revoke button.

OAuth Clients

Every application connecting with Showpad APIs 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.

Manage clients

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

Add clients

  1. 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.

New client

  1. 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 Key Holder.

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.

ScopeDescription
refresh_tokenAllows the refresh of access tokens.
read_user_managementAllows read access for user data (includes users, usergroups and user permissions).
write_user_managementAllows write access for user data (includes users, usergroups and user permissions).
read_contentprofile_managementAllows read access for content profile-related resources (content profiles, assets, tags, tickets and comments).
write_contentprofile_managementAllows write access for content profile-related resources (content profiles, assets, tags, tickets and comments).
read_division_managementAllows read access for division-related resources (divisions and division permissions).
write_division_managementAllows write accesss for division-related resources (divisions and division permissions).

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:

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:

Server-side flow Diagram

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

ParameterRequiredDescription
client_idYesThe ID assigned to your OAuth2 client during registration in the Online Platform.
redirect_uriYesThe callback URL specified when registering the OAuth2 client. This URL is called after a successful authorization request.
response_typeYesThis should be code.
stateNoAdditional URL-encoded data to be returned via the callback URL.
scopeNoSpecifies the scope limitations of the request. You cannot specify a scope the client is not authorized to use.

Process Description

StepDescription
1 & 2User 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.
3Client 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.
4Create authorization code. Once authorized, the user is then redirected to the redirect URL with the following parameters:

ParameterDescription
codeThe 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.
stateThe state that was sent as a parameter in the first step.
5Request 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:

ParameterRequiredDescription
client_idYesThe ID of your OAuth2 client as obtained from the Online Platform.
client_secretYesAvailable in the Online Platform after creating the OAuth client.
grant_typeYes Should be: authorization_code
code YesThe authorization code provided in step 4.
redirect_uriYesThe callback URL specified in the Online Platform when the OAuth2 client was registered.
stateNoAdditional 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:

ParameterRequiredDescription
grant_typeYesShould be: refresh_token
refresh_tokenYesThe refresh token obtained during step 8 of the original authentication flow.
stateNoAdditional URL-encoded data that will be returned.
client_idYesThe ID of your OAuth2 client as obtained from the Online Platform.
client_secretYesAvailable 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:

ParameterRequiredDescription
grant_typeYesShould be password
usernameYesThe user's username.
passwordYesThe password for the username.
stateNoAdditional URL-encoded data that will be returned.
client_idYesThe ID of your OAuth2 client as obtained from the Online Platform.
client_secretYesAvailable 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"
}

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://customer.api.showpad.com/v4/users \
--header 'Authorization: Bearer <myAPItoken>' \
--header 'Content-Type: application/json'