API authentication and token security
Astro authenticates programmatic and UI-driven API requests with bearer tokens. This page describes the token types Astro supports, how each is validated, default and configurable lifetimes, rotation and revocation behavior, and current limitations. Use it to evaluate the Astro API authentication model from a security perspective.
For step-by-step instructions on creating each token type, see Organization API tokens, Workspace API tokens, Deployment API tokens, and Authenticate an automation tool to Astro.
Token types
Astro supports two categories of bearer tokens:
- Customer-created API tokens. You create these tokens in the Astro UI or with the Astro API to authenticate automation, CI/CD pipelines, and external integrations. Astro scopes each token to an Organization, Workspace, or Deployment.
- UI-issued short-lived tokens. The Astro UI requests these tokens from its
/tokenendpoint after you sign in. The UI and Astro CLI use them to make authenticated requests on your behalf during an active session.
The following table summarizes each token type:
Token validation
All Astro bearer tokens are JSON Web Tokens (JWTs). Astro validates each request by verifying the token’s signature, issuer, audience, and expiration (exp) claim before authorizing the request.
- Customer-created Organization, Workspace, and Deployment API tokens are JWTs that Astro signs and validates.
- UI-issued session tokens are JWTs that Auth0 signs. Astro validates these tokens through the Auth0 Identifier First Authentication flow.
Astro rejects tokens with invalid signatures, missing or incorrect claims, or expired exp values.
Token lifetime
You control how long customer-created API tokens remain valid. When you create an Organization, Workspace, or Deployment API token, set the Expiration field to the number of days that the token can be used. After the expiration, Astro rejects the token. Astronomer recommends setting the shortest expiration that meets your automation requirements.
UI-issued session tokens have a default lifetime of 8 hours. The Astro UI can extend an active session up to 30 days through a refresh token flow. After this maximum, you must sign in again to obtain a new session token.
Token rotation and revocation
Astro provides rotation and revocation controls for customer-created API tokens:
- Rotation. You can rotate an Organization, Workspace, or Deployment API token from the Astro UI or with the Astro API. Rotation issues a new token value and invalidates the previous value. See Rotate an Organization API token for an example.
- Revocation. Deleting an API token immediately revokes it. Astro rejects any subsequent request that presents the deleted token.
UI-issued session tokens can’t be rotated directly. To invalidate an active session, sign out of the Astro UI, which ends the session and invalidates the associated refresh token.
Token rotation replaces the previous token value immediately. The previous value stops working as soon as Astro issues the new value. Plan rotations to minimize the gap between updating the new value in your automation and the previous value becoming invalid.
Current limitations
The Astro API authentication model has the following current limitations:
- No Organization-wide maximum-lifetime policy. Organization Owners can’t enforce a maximum expiration across all API tokens created in an Organization. Each token creator sets the expiration at creation time. Astronomer recommends defining and communicating an internal policy for maximum token lifetimes, and auditing existing tokens through the Astro UI.
- No grace period during rotation. The public rotation endpoint doesn’t allow the previous token value to remain valid alongside the new value for a grace period. To minimize automation downtime, update the new token value in all consumers as soon as you rotate the token.
