Skip to main content

How to obtain an API token

The Spectra Assure Portal API provides a different way to interact with Portal features. As a result, a Portal account is required to use the API. More specifically, a token associated with a Portal account is required for authentication in every request to the API.

Before you can start using the API, you must create a Personal Access Token for your Portal account.

Every Portal user can create Personal Access Tokens for their account. When created, the tokens are automatically scoped to the access level of the user account.

If you're not able to obtain a token for your Portal account, contact your Organization Administrator for assistance.

Working with Personal Access Tokens​

In the Portal, you can perform the following actions with Personal Access Tokens:

You can create as many tokens as you want and revoke them at any time.

Revoking tokens

Make sure to update any scripts or processes that rely on tokens you plan to revoke, as they will stop working when the tokens are no longer active.

Create a token​

  1. To create a token for API authentication, log in to your Portal instance.

  2. Select your username in the upper right corner. In the dropdown that opens, choose User Settings.

  3. On the page that opens, select Personal Access Tokens in the sidebar on the left.

  4. If you haven't previously created any tokens, the page is empty and displays the message "No tokens have been found". Select Generate New Token above the Tokens list.

Tokens page in the portal with the list of generated tokens for the user

  1. In the dialog that opens, provide a custom name for your token (for example, "My Portal API token"). The name is only used in the Portal to help you distinguish your tokens. Set the token expiration date or use the default value (90 days).

  2. Select Generate to finish creating your token.

  3. In the dialog that opens, copy the token and store it in a safe place. This is the only way to obtain the token you just created!

After closing the dialog, your newly created token is listed on the Tokens page. For every token on this page, the last used date is displayed alongside the expiration date.

You can now use the token you copied and saved in Step 7 to send your first API request.

Revoke a token​

Tokens cannot be modified in any way after they've been created. They can only be revoked.

  1. To revoke a specific token, select Revoke in the Tokens list.

  2. In the dialog that opens, you must confirm that you want to revoke the token by selecting Revoke. If you change your mind, select Cancel to exit the dialog.

Revoked tokens are immediately inactivated and removed from the Tokens page.

You can also revoke all tokens at once by selecting Revoke All Tokens above the Tokens list.

In the dialog that opens, you must type in revoke-all to confirm the action, then select Revoke. To exit the dialog and keep all tokens, select Cancel at any time.

Expired tokens​

Tokens can have an expiration date, which is set by the user when creating a token. When a token expires, it stops functioning and is essentially like a revoked token. The difference is that expired tokens are not automatically removed from the Tokens list when they expire. Instead, users can choose to manually remove expired tokens if they want to.

If any of your tokens have expired, they will be displayed in the Tokens list as greyed out. Their last used date will be displayed alongside their expiration date.

To remove an expired token, select Delete. The token is immediately removed from the Tokens page.