Skip to main content
A Deployment API token is a credential that you can use to programmatically access a specific Deployment. They are a direct replacement for Deployment API keys, which aren’t supported. Using a Deployment API token, you can: Use this document to learn how to create and manage API tokens. To use your API token in an automated process, see Authenticate an automation tool. For an overview of how Astro authenticates API requests, including JWT validation, token lifetimes, and rotation behavior, see API authentication and token security.

​
Deployment API token permissions

Unlike Workspace API tokens and Organization API tokens, Deployment API tokens aren’t scoped to a specific user role. Deployment API tokens have the same permissions as the Workspace Operator role, but only for Deployment-level operations. For example, an API token can create a Deployment environment variable but, unlike a Workspace Operator, it can’t create an Astro alert because alerts apply to the whole Workspace.
You can manage Dag roles and the Deployment role for a Deployment API token from its access management page. See Manage Deployment API token access.
A new Astro UI is hereAstronomer has redesigned the Astro UI. Try the new experience and switch your instructions using the New Astro UI and Legacy UI tabs on this page. Your selection is remembered across the docs.

​
Create a Deployment API token

  1. In the Astro UI, click Deployments, then select a Deployment.
  2. Click Access > API Tokens.
  3. Click + Add API Token > New Deployment API Token.
  4. Configure the new Deployment API token:
    • Name: The name for the API token.
    • Description: (Optional) The Description for the API token.
    • Type: Standard or Direct Access. See Direct access API tokens for more information.
    • Deployment Role: (Enterprise plan only) Choose the Deployment-level role and permissions that the API token will have. See Customize Deployment roles.
    • Expiration: The number of days that the API token can be used before it expires.
  5. Click Add API token. A confirmation screen showing the token appears.
  6. Copy the token and store it in a safe place. You won’t be able to retrieve this value from Astro again.

​
Direct access API tokens

A direct access API token grants the ability to bypass the control plane in the event of a system outage. The role assigned to a direct access Deployment API token can’t be changed after the token is created.
Only Organization Owners can create direct access Deployment API tokens.

​
Assign an Organization or Workspace API token to a Deployment

To centralize API token management, you can add an Organization or Workspace API token to a Deployment instead of creating a dedicated Deployment API token. Deployment-scoped API tokens are useful if you want to manage API tokens from the Organization level on a single screen, or you want to use a single API token for multiple Deployments. Deployment-scoped API tokens are functionally identical to dedicated Deployment API tokens, except that you can only rotate, update, or delete them within their original scope.
  1. In the Astro UI, click Deployments, then select a Deployment.
  2. Click Access > API Tokens.
  3. Click + Add API Token, then click Assign Workspace API Token or Assign Organization API Token.
  4. Configure the new Deployment API token:
    • Workspace/ Organization API Token: Select the API token you want to assign to the Deployment.
    • Deployment Role: Select the role that the API token has in the Deployment.
  5. Click Update API Token.

​
Manage Deployment API token access

You can view and manage the roles for a Deployment API token from its access management page.
  1. In the Astro UI, click Deployments, then select a Deployment.
  2. Click Access > API Tokens.
  3. Click the row for the API token you want to manage.
The token access management page shows the following information and management options:
  • Deployment Role: View or update the token’s Deployment role. Click Edit to change the role, then click Update API Token.
  • Dag Roles: View and manage the token’s Dag role assignments. Click + Dag to add a Dag role. To edit or remove a Dag role, open the More actions menu (⋯) next to the Dag entry. See Dag-level access control for more information about Dag roles.

​
Update or delete a Deployment API token

If you delete a Deployment API token, make sure that no existing CI/CD workflows are using it. After it’s deleted, an API token can’t be recovered. If you unintentionally delete an API token, create a new one and update any CI/CD workflows that used the deleted API token.
  1. In the Astro UI, click Deployments, then select a Deployment.
  2. Click Access > API Tokens.
  3. Open the More actions menu (⋯) next to your API token, then click Edit Token.
  4. Update the name or description of your token, then click Update API Token.
  5. (Optional) To delete a Deployment API token, click Delete API Token, enter Delete, and then click Yes, Continue. If you’re editing a Deployment-scoped API token, click Remove API token instead to unassign the API token from the Deployment.

​
Rotate a Deployment API token

Rotating a Deployment API token lets you renew a token without needing to reconfigure its name, description, and permissions. You can also rotate a token if you lose your current token value and need it for additional workflows. When you rotate a Deployment API token, you receive a new valid token from Astro that can be used in your existing workflows. The previous token value becomes invalid and any workflows using those previous values stop working.
  1. In the Astro UI, click Deployments, then select a Deployment.
  2. Click Access > API Tokens.
  3. Open the More actions menu (⋯) next to your API token, then click Rotate Token. Type in ROTATE to confirm, and click Yes, Continue. The Astro UI rotates the token and shows the new token value.
  4. Copy the new token value and store it in a safe place. You won’t be able to retrieve this value from Astro again.
  5. In any workflows using the token, replace the old token value with the new value you copied.

​
Use a Deployment API token with the Astro CLI

To use a Deployment API token with Astro CLI, specify the ASTRO_API_TOKEN environment variable in the system running the Astro CLI:
After you configure the ASTRO_API_TOKEN environment variable, you can run Astro CLI commands related to the Deployment for which the Deployment API token was created. For example, astro deployment inspect or astro deployment logs. When using a Deployment API token for automation, Astronomer recommends storing ASTRO_API_TOKEN as a secret.

​
Use a Deployment API token for CI/CD

You can use Deployment API tokens and the Astro CLI to automate various Deployment management actions in CI/CD. For all use cases, you must make the following environment variable available to your CI/CD environment:
After you set this environment variable, you can run Astro CLI commands from CI/CD pipelines without needing to manually authenticate to Astro. For more information and examples, see Automate code deploys with CI/CD.