API Keys

Introduction

The Tarsal API uses JSON web tokens (JWT). It authenticates request tokens and responds with access tokens.

JWTs are objects for secure, stateless communication between Tarsal and your API integration (client application). Authentication request tokens contain information from your Tarsal account and are signed with a shared secret. Access tokens are reusable, long-lived credentials that authorize API use without a password-based login and are issued after successful authentication.

Shared secrets and API keys are unique alphanumeric strings for application and user identity and validation. Tarsal automatically generates a shared secret upon account creation. API keys, or application secrets, are generated on demand and specific to each integration.

The following JWT configuration variables and portal values comprise the data for an API authentication request token:

See API Keys Overview for more information.

The Tarsal portal provides key management and JWT values at https://app.tarsal.cloud/settings/api-keys, including:

• Shared secret management
  • Viewing the shared secret
  • Regenerating the shared secret
• API key management
  • Adding API keys
  • Updating API keys
  • Regenerating API keys
  • Removing API keys

For security, API key values are visible in the portal when created or regenerated; they aren’t retrievable after display. The shared secret, however, is always viewable, and unlike API keys, it is not removable.

⚠️

Key Storage

Store the shared secret and keys securely! Tarsal can’t recover your API keys.

Overview

Tarsal API authentication includes the following steps:

1. Construct a JWT payload with the required configuration variables and values.
2. Encode the JWT using the payload, shared secret, and signing algorithm.
3. Supply the JWT in an API authentication request.
4. Send the response access token in all following API requests.

See the API Authentication Recipe for details.

❗️

Lost Keys

If your API key is lost, regenerate it and update your integration.

After regenerating the shared secret or keys, your integration will immediately stop working without sending a new access token in API requests.

Managing the Shared Secret

The following steps assume you’re an Admin and logged in to the portal.

Viewing the Shared Secret

To view the account’s shared secret:

1. Go to Account > Settings from the left navigation.
2. Click the API Keys tab at the top.
3. Click the API Shared Secret button on the upper right.
4. In the modal window, click the clipboard icon () on the right to copy the shared secret to your clipboard. Record the value in a safe location.
5. Click the Cancel button.

📘

Request Token Value

API Shared Secret provides the value for SHARED_SECRET in the authentication request token.

Regenerating the Shared Secret

❗️

Before You Begin

Regenerate the shared secret as needed, but note that it immediately invalidates all your API integrations. For each integration, encode a request token with the new shared secret and request a new access token.

To regenerate the shared secret:

1. Go to Account > Settings from the left navigation.
2. Click the API Keys tab at the top.
3. Click the API Shared Secret button on the upper right.
4. In the modal window
   1. Click the Regenerate button.
   2. Click the clipboard icon () on the right to copy the shared secret to your clipboard. Record the value in a safe location.
5. Click the X on the upper right to close the modal window.

Managing API Keys

The following steps assume you’re an Admin and logged in to the portal.

❗️

Before You Begin

Record and store API keys in a safe place!

Adding an API Key

To create a new API key:

1. Go to Account > Settings from the left navigation.
2. Click the API Keys tab at the top.
3. Click the API Shared Secret button on the upper right.
4. In the modal window
   1. Enter an Application Name.
   2. Enter an optional Description.
   3. Select Member or Admin from the drop-down list.
   4. Click the Save button.
   5. Click the clipboard icon () to the right of Application Name (appname) to copy it to your clipboard. Record the value in a safe location.
   6. Click the clipboard icon () to the right of Application Secret (appsecret) to copy it to your clipboard. Record the value in a safe location.
   7. Click the Done button.

📘

Request Token Values

In the authentication request token, Application Name (appname) provides the value for APPNAME, and Application Secret (appsecret) for APPKEY.

📘

Choosing an API Key Role

API keys have roles, unlike shared secrets. Select the most secure role based on your integration’s functionality. See Roles for more details.

Updating an API Key

To edit an API key’s associated information:

1. Go to Account > Settings from the left navigation.
2. Click the API Keys tab at the top.
3. Click . . . (three dots) under the Action column for the desired key.
4. In the drop-down menu, select Edit.
5. In the modal window
   1. Update the Application Name.
   2. Update the optional Description.
   3. Update the Role in the drop-down list.
6. Click the Save button.

❗️

Changing API Key Information

Your integration will stop functioning if the application name or role is updated. Send a new request token to receive a new access token.

Regenerating an API Key

New API keys for existing integrations are sometimes necessary. For example, a compromised API key requires a replacement.

❗️

Before You Begin

API key regeneration immediately invalidates your API integration. Make sure to request a new access token using the regenerated key!

To regenerate an API key:

1. Go to Account > Settings from the left navigation.
2. Click the API Keys tab at the top.
3. Click . . . (three dots) under the Action column for the desired key.
4. In the drop-down menu, select Regenerate.
5. In the modal window
   1. Click the Regenerate button.
   2. Under API Key, locate Application Secret (appsecret).
   3. Click the clipboard icon () on the right to copy the API key (application secret) to your clipboard. Record the value in a safe location.
6. Click the Done button.

The application name, description, and role remain when regenerating an API key.

Removing an API Key

❗️

Before You Begin

Deleted API keys aren’t recoverable. Before removing a key, ensure an integration doesn’t use it.

To delete an API key:

1. Go to Account > Settings from the left navigation.
2. Click the API Keys tab at the top.
3. Click . . . (three dots) under the Action column for the desired key.
4. In the drop-down menu, select Remove.
5. In the modal window, click the Delete API Key button.