Create and manage Organization API tokens

Use Organization API tokens to automate across all Workspaces in your Organization, such as creating Deployments and managing users as part of your CI/CD pipelines. Organization API tokens are particularly helpful for automating:

• Creating Workspaces.
• Inviting users to an Organization or Workspace. See Add a group of users to Astro using the Astro CLI.
• Creating and updating Deployments using a Deployment file.
• Exporting audit logs.
• Gathering metadata about Deployments using the Airflow REST API.
• Completing any of the actions you can complete with a Workspace API token or Deployment API token across all Deployments in your Organization.

For Deployments running Astro Runtime 3.1-12 or later, you can assign Dag-level roles to Organization, Workspace, and Deployment API tokens. See Assign Dag roles to API tokens.

Create an Organization API token

1. In the Astro UI, click Organization Settings.

2. Go to Access Management > API Tokens.

3. Click + API Token.

4. Configure the new Organization API token:

• Name: The name for the API token.
• Description: Optional. The Description for the API token.
• Organization Role: The role that the API token can assume. See User permissions.
• Expiration: The number of days that the API token can be used before it expires.

1. Click Create API token. A confirmation screen showing the token appears.
2. Copy the token and store it in a safe place. You will not be able to retrieve this value from Astro again.

Update or delete an Organization API token

If you delete an Organization API token, make sure that no existing automation 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 automation workflows that used the deleted API token.

1. In the Astro UI, click Organization Settings.

2. Go to Access Management > API Tokens.

3. Open the action menu (⋯) then click Edit Token next to your API token.

4. Update the name, description, or Organization role of your token, then click Update API Token.

5. Optional. To delete an Organization API token, click Delete Token, enter Delete, and then click Yes, Continue.

Rotate an Organization API token

Rotating an Organization 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 an Organization 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 Organization Settings.

2. Go to Access Management > API Tokens.

3. Click Edit next to your API token.

4. Click Rotate token. The Astro UI rotates the token and shows the new token value.

5. Copy the new token value and store it in a safe place. You will not be able to retrieve this value from Astro again.

6. In any workflows using the token, replace the old token value with the new value you copied.

Use an Organization API token with the Astro CLI

To use an Organization API token with Astro CLI, specify the ASTRO_API_TOKEN environment variable in the system running the Astro CLI.

For example, to automate Astro CLI commands on a Mac, run the following command to set a temporary value for the environment variable:

1
export ASTRO_API_TOKEN=<your-token>

After you set the variable, you can run astro deployment, astro workspace, and astro organization commands for your Workspace without authenticating yourself to Astronomer. Astronomer recommends storing ASTRO_API_TOKEN as a secret before using it to automate the Astro CLI for production workflows.

Use an Organization API token for CI/CD

You can use Organization API tokens and the Astro CLI to automate various Organization, Workspace, and Deployment management actions in CI/CD.

For all use cases, you must make the following environment variable available to your CI/CD environment:

ASTRO_API_TOKEN=<your-token>

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.