Authentication

Every API request to Showpad requires an access token, a credential that proves your identity and determines what you can access. Showpad uses OAuth2, an industry-standard protocol that works over HTTPS, to issue these tokens. OAuth2 is more secure than sharing passwords because tokens can be scoped to specific permissions and revoked at any time.

What you'll learn:

Generate and use Personal API Tokens
Register OAuth clients and configure scopes
Authenticate using Authorization Code, Refresh Token, or User Credentials

TL;DR

Quick testing? Use a Personal API Token. Generate one in Admin App → Settings → API Tokens.
Users log in with their Showpad account? Use Authorization Code. Most secure for apps acting on behalf of users.
Automated script or service account? Use User Credentials. Simpler when you control the credentials.
Token expired? Use your Refresh Token to get a new one (access tokens last 1 hour, refresh tokens last 14 days)

Prerequisites

Plan: Ultimate, Advanced, or Expert
Permissions: Administrator access to Showpad's Admin App

Which Method to Use?

Authentication overview

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 Settings of the Admin App.

Click the API Tokens link.
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.
Click the Add button.
Copy the displayed token and store it in a safe location for future use.

warning
This token is only displayed once. You cannot retrieve it later.
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 Settings of the Admin App.

Click the Manage OAuth Clients link.
Click the + icon to add a new OAuth2 Client.
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.
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 related 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 related resources	`read_division_management`	Allows read access for Division-related resources (Divisions and Division permissions).
Edit Division related resources	`write_division_management`	Allows write access for Division-related resources (Divisions and Division permissions).
AppsDB online integrations	`appsdb_online_integrations`	Enables usage of AppsDB without a Showpad App. This feature requires activation. Contact your Customer Success Manager if you're interested.

OAuth Grant Types

A "grant type" is simply the method your application uses to get an access token. Showpad supports three grant types:

Grant Type	When to Use
Authorization Code (server-side)	You're building a server-side application where users log in with their Showpad credentials. This is the most secure option for user-facing applications.
Refresh Token	You already have an access token that's about to expire and need a new one without asking the user to log in again.
User Credentials	You're building a backend service or script where you control both the application and the user credentials. Simpler than Authorization Code but requires storing passwords.

Authorization Code

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

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

This request initiates the following authorization process:

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

Parameter	Required	Description
`client_id`	Yes	The URL-encoded ID assigned to your OAuth2 client during registration in the Admin App.
`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 isn't authorized to use.

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

Refresh Token

Access tokens expire after 1 hour. Instead of asking users to log in again, use your refresh token to get a new access token.

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

Include these parameters in the request body:

Parameter	Required	Description
`grant_type`	Yes	Set this to `refresh_token`
`refresh_token`	Yes	The refresh token from your original authentication
`client_id`	Yes	Your OAuth2 client ID
`client_secret`	Yes	Your OAuth2 client secret
`state`	No	Any data you want returned

Example 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

Refresh tokens are valid for 14 days. After that, the user must authenticate again.

User Credentials

Use this grant type when you control both the application and the user's credentials. This is simpler than Authorization Code, but requires your application to handle the username and password directly.

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

Include these parameters in the request body:

Parameter	Required	Description
`grant_type`	Yes	Set this to `password`
`username`	Yes	The user's username
`password`	Yes	The user's password
`client_id`	Yes	Your OAuth2 client ID
`client_secret`	Yes	Your OAuth2 client secret
`state`	No	Any data you want returned

Example Request

cURL
JavaScript
Python

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'

const response = await fetch('https://{{subdomain}}.showpad.biz/api/v3/oauth2/token', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/x-www-form-urlencoded',
  },
  body: new URLSearchParams({
    grant_type: 'password',
    username: 'johnqpublic',
    password: 'mystrongpassword',
    client_id: 'FRZXGQFNMILL1YUCX3HMF350WM3ZRYTLXEBNMNIFHNU5S6WZJDOBG',
    client_secret: 'e75i3nhgclzcf5hrspah1wpak5efut1kj45b9mxl',
  }),
});

const data = await response.json();
console.log(data);

import requests

url = "https://{{subdomain}}.showpad.biz/api/v3/oauth2/token"
headers = {"Content-Type": "application/x-www-form-urlencoded"}
data = {
    "grant_type": "password",
    "username": "johnqpublic",
    "password": "mystrongpassword",
    "client_id": "FRZXGQFNMILL1YUCX3HMF350WM3ZRYTLXEBNMNIFHNU5S6WZJDOBG",
    "client_secret": "e75i3nhgclzcf5hrspah1wpak5efut1kj45b9mxl"
}

response = requests.post(url, headers=headers, data=data)
print(response.json())

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

Using API Tokens

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

cURL
JavaScript
Python

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

const response = await fetch('https://{{subdomain}}.api.showpad.com/v4/users', {
  method: 'GET',
  headers: {
    Authorization: 'Bearer <myAPItoken>',
    'Content-Type': 'application/json',
  },
});

const data = await response.json();
console.log(data);

import requests

url = "https://{{subdomain}}.api.showpad.com/v4/users"
headers = {
    "Authorization": "Bearer <myAPItoken>",
    "Content-Type": "application/json"
}

response = requests.get(url, headers=headers)
print(response.json())

Security Best Practices

Protect Your Tokens

Never commit tokens to version control. Add .env files to your .gitignore.
Use environment variables. Store tokens in SHOWPAD_API_TOKEN rather than hardcoding them.
Rotate tokens regularly. Especially for production integrations.
Use minimal scopes. Only request the permissions your application actually needs.
Revoke unused tokens. Remove tokens for applications no longer in use.

Token Storage

Environment	Recommended Storage
Local development	Environment variables or `.env` file (never committed)
CI/CD pipelines	Secret management (GitHub Secrets, GitLab CI Variables, etc.)
Production servers	Secret manager (AWS Secrets Manager, HashiCorp Vault, etc.)
Browser apps	Never store tokens in localStorage; use secure, httpOnly cookies

Error Handling

If authentication fails, the API returns an error response with details about what went wrong. For a complete list of error codes and troubleshooting guidance, see Error Codes.

Token Expired?

If you receive a 401 error, your access token has likely expired. Use your refresh token to get a new one without requiring the user to log in again.

Next Steps

Now that you can authenticate, explore these related topics:

CORS - Configure cross-origin requests for browser-based apps
API Testing - Test your authenticated requests directly in the docs
Error Codes - Understand error responses and troubleshoot issues

Was this page helpful?

Which Method to Use?​

Personal API Tokens​

OAuth Clients​

Registration​

Scopes​

OAuth Grant Types​

Authorization Code​

Example Response​

Refresh Token​

Example Response​

User Credentials​

Example Request​

Example Response​

Using API Tokens​

Security Best Practices​

Token Storage​

Error Handling​

Next Steps​

Which Method to Use?

Personal API Tokens

OAuth Clients

Registration

Scopes

OAuth Grant Types

Authorization Code

Example Response

Refresh Token

Example Response

User Credentials

Example Request

Example Response

Using API Tokens

Security Best Practices

Token Storage

Error Handling

Next Steps