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.

(Advanced) Logging in using an access token

You may use an access token to log into Spell. This feature is only intended to be used by users that want with interactive sessions in environments that do not support the default web-based Spell login flow.

For example, this feature enables running Spell commands from a remote machine your have SSHed into. The default flow will not work in this case because you most likely will not have access to a web browser on the remote machine (unless you additionally configure remote machine access).

This flow should not be used for authentication in non-interactive environments. For example, you should not use this flow for running Spell commands within CI/CD. For that, export a session token as an environment variable instead (see the section "Using an access token" for details).

To begin, log in using the web browser, then navigate to Settings -> Account in the web console. Create a new temporary access token and copy it to your clipboard. Export your token and owner to the SPELL_TOKEN and SPELL_OWNER environment variables, as documented in the section "Using an access token", then run spell login. You will be prompted for your account email and, assuming the token is valid, logged in on that machine.

At this point you can unset the environment variables and proceed as normal. You should probably delete your temporary access token as well, unless you expect to use it for something else.