Skip to main content

Access tokens

An access token lets a script, CI pipeline, or app act on your Mastra platform organization without an interactive login. The dashboard calls them API keys. Use access tokens to:

  • Run mastra deploy and other CLI commands in CI. See CI/CD.
  • Authenticate apps that use Connect or @mastra/platform outside a platform deploy, such as on your local machine.

A token belongs to one organization. It's tied to the member who created it and stops working if that member leaves the organization. Admins and members can create tokens. Viewers can't.

Create an access token
Direct link to Create an access token

You can create a token in the dashboard or with the CLI. Either way, the token is shown once. Copy it before you close the dialog or terminal, because you can't see it again.

In the dashboard
Direct link to In the dashboard

  1. Open your organization's settings in the Mastra platform and select API Keys.
  2. Select Create API key.
  3. Enter a name that identifies where you'll use the token, such as CI Deploy.
  4. Select Create, then copy the token.

With the CLI
Direct link to With the CLI

Log in, then create a token for the current organization:

mastra auth login
mastra auth tokens create ci-deploy

The CLI uses the organization set by mastra auth orgs switch, or MASTRA_ORG_ID when it's set.

Use an access token
Direct link to Use an access token

Different tools read the token from different environment variables:

VariableRead by
MASTRA_API_TOKENThe mastra CLI. When it's set, commands such as mastra deploy run without an interactive login.
MASTRA_PLATFORM_ACCESS_TOKEN@mastra/platform and @mastra/connect.

For example, to deploy from CI to the production environment:

MASTRA_API_TOKEN=your-token \
MASTRA_ORG_ID=your-org-id \
MASTRA_PROJECT_ID=your-project-id \
mastra deploy --yes

MASTRA_PROJECT_ID selects the project, not the environment. Without --env, mastra deploy deploys to production. To deploy to another environment, add --env, for example mastra deploy --env staging --yes.

Store tokens as secrets in your CI provider or hosting platform. Don't commit them to your repository.

List and revoke tokens
Direct link to List and revoke tokens

The API Keys page lists your organization's tokens with their names, creation dates, and last-used dates. To list them from the terminal, run:

mastra auth tokens

To revoke a token, select its remove icon on the API Keys page, then select Revoke, or run:

mastra auth tokens revoke <token-id>

A revoked token stops working immediately, and you can't restore it. Any CLI sessions, CI pipelines, or telemetry ingestion that use it lose access. To replace a token without downtime:

  1. Create a new token.
  2. Update every place that uses the old token, such as CI secrets and environment variables.
  3. Redeploy or restart affected environments. Running deploys keep the old value until they restart.
  4. Confirm that each service works with the new token.
  5. Revoke the old token.
On this page