> ## Documentation Index
> Fetch the complete documentation index at: https://astronomer.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Create and manage Deployment API tokens
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:
* [Push code](/docs/astro/deploy-code) to a Deployment.
* Update the Deployment's [environment variables](/docs/astro/environment-variables).
* Update a Deployment's configurations. See [Manage Deployments as code](/docs/astro/manage-deployments-as-code).
* Make requests to update your Deployment's Airflow environment using the [Airflow REST API](/docs/astro/airflow-api).
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](/docs/astro/automation-authentication). For an overview of how Astro authenticates API requests, including JWT validation, token lifetimes, and rotation behavior, see [API authentication and token security](/docs/astro/api-authentication).
## Deployment API token permissions
Unlike Workspace API tokens and Organization API tokens, Deployment API tokens aren't scoped to a specific [user role](/docs/astro/user-permissions). Deployment API tokens have the same permissions as the [Workspace Operator](/docs/astro/user-permissions#workspace-roles) role, but only for Deployment-level operations. For example, an API token can create a Deployment [environment variable](/docs/astro/environment-variables) but, unlike a Workspace Operator, it can't create an [Astro alert](/docs/astro/alerts) 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](#manage-deployment-api-token-access).
**A new Astro UI is here**
Astronomer 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](#direct-access-token-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](/docs/astro/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.
1. In the Astro UI, open your Workspace, then open the Deployment you want to create an API token for.
2. Click **Access**.
3. Click **API Tokens**, then click **+ Deployment API Token**. In the dropdown menu that appears, click **Add 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](#direct-access-token-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](/docs/astro/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**.
1. In the Astro UI, open your Workspace, then open the Deployment you want to create an API token for.
2. Click **Access**.
3. Click **API Tokens**, then click **+ Deployment API Token**. In the dropdown menu that appears, click either **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.
1. In the Astro UI, open your Workspace, then open the Deployment that the API token belongs to.
2. Click **Access**.
3. Click **API Tokens**, then 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](/docs/astro/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.
1. In the Astro UI, open your Workspace, then open the Deployment that the API token belongs to.
2. Click **Edit** next to your API token.
3. Update the name or description of your token, then click **Save Changes**.
4. (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.
1. In the Astro UI, open your Workspace, then open the Deployment that the API token belongs to.
2. Click **Edit** next to your API token.
3. Click **Rotate token**. 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 will not 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:
```sh wrap theme={null}
export ASTRO_API_TOKEN=
```
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`](/docs/cli/v1.43/astro-deployment-inspect) or [`astro deployment logs`](/docs/cli/v1.43/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:
```text wrap theme={null}
ASTRO_API_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](/docs/astro/set-up-ci-cd).