Access Tokens

Spell access tokens are long-lived user credentials designed for use within automated settings (such as CI/CD).


For an example application of access tokens see our blog post "Implement CI/CD with GitHub Actions".

Creating an access token

Access tokens can be created using either the Spell CLI or the Spell web console. Keep in mind that access tokens must be uniquely named.


After creation, the token itself is NOT recoverable! This is for security reasons, so be sure to store it somewhere safe and secure.

With the CLI, the command is spell access-tokens create:

$ spell access-tokens create ci-token
New Access Token 'ci-token' created at Jul 29 15:40
NOTE: this token is not recoverable, so save it somewhere safe.

With the web console, navigate to Settings -> Account in the sidebar, and you will find a table of all your access tokens, with a button allowing you to create a new one.

Image of the access token table.

Click the CREATE ACCESS TOKEN button and enter a valid and unique name in the modal to create a new access token. On success the modal will contain the value of the access token itself, be sure to store it before closing the modal.

Using an access token

One of the primary use cases for access tokens is for writing code that interacts with Spell. Spell's Python API is designed for this use case, and you can use an access token to authenticate from within Python like so:

import spell.client
client = spell.client.SpellClient(token='<auth token>', owner='<owner>')

Where <owner> is the name of your organization. Access tokens can be used to authenticate to any organization your user account is a member of, so you need to specify which organization (owner) you are authenticating to. To learn more, refer to the section "Switching Users" in the User Management documentation.

Alternatively, use the SPELL_TOKEN and SPELL_OWNER enviornment variables:

$ export SPELL_TOKEN='<auth token>'
$ export SPELL_OWNER='<owner>'

And then in Python, use the standard from_environment() call to create the Spell client:

import spell.client
client = spell.client.from_environment()

This form of authorization works with the Spell CLI as well.

Viewing access tokens

To see your existing access tokens navigate to Settings -> Account in the web console or use spell access-tokens list. From here you can see all the tokens and the times that they were created and last used.

$ spell access-tokens list
name    created at    last used at
tokenX  1 hour ago    <unused>
tokenY  1 hour ago    15 minutes ago
tokenZ  22 hours ago  <unused>

Deleting access tokens

Deleting an access token can be done in the web console or the CLI. Deleting an access token will free up the name to be used for a new access token, while forever invalidating the authentication of the deleted token itself.

In the CLI use the command spell access-tokens delete <name>. In the web console you can click the blue x button on the tokens list page.