API Keys

Rotate a key's token

Issues a new token for the key. The old token stops working immediately. The key keeps its ID, name and limit. If the key belongs to a Shopify, BigCommerce or WordPress Connect integration, the response includes integration_warning: that integration stops working until it reconnects.

Send an Idempotency-Key header to retry safely.

post/api_keys/{id}/rotation

Request

  • Base URL: https://alttext.ai/api/v1
  • URL: https://alttext.ai/api/v1/api_keys/{id}/rotation
  • Auth: API key in header X-API-Key

Path parameters

idinteger required

The ID of the key.

Headers

Idempotency-Keystring

A unique string you generate, such as a UUID. Retrying the same request with the same Idempotency-Key within 24 hours returns the original result instead of creating or rotating a second time. A retry is the same request only when the path and body match; otherwise you get idempotency_key_reused. A replay returns the token only while it is still the key's current token. After a later rotation or revocation it returns 409 idempotent_replay_superseded instead. A request that failed is not stored, so retrying it runs again.

Response

The key with its new token.

idinteger
namestring
kind'site'

Always site here. Full-access keys are created and managed in the dashboard only.

origin'unknown' | 'dashboard' | 'api' | 'shopify' | 'bigcommerce' | 'wordpress_connect'

Where the key was created.

integration'shopify' | 'bigcommerce' | 'wordpress_connect' | 'null' nullable

The integration that created and uses this key, or null. Rotating or revoking an integration key stops that integration until it reconnects.

status'active' | 'revoked'
tokenstring nullable

The key's token, or null once the key is revoked or when an assistant connection without write access reads it. Tokens begin with atai_. Keys created before that format existed keep their original tokens, which stay valid. Treat the token as a secret.

token_hintstring nullable

The last four characters of the token, or null once the key is revoked.

usage_limitinteger nullable

The recorded-usage threshold that stops new requests this billing period. In-flight work can still be charged beyond it. null means no limit.

credits_usedinteger

Credits this key has used this period, counted against usage_limit.

billable_creditsinteger

Every credit charged to the account through this key this period, whether or not the charge crossed the key's limit.

billable_completeboolean

Whether every charge in the current period was tracked by the billing-aware release after the operator's verified old-task drain cutoff. False when tracking is incomplete or the cutoff is absent.

period_startstring date-time nullable

When the current period started, if the key has been reset.

resets_atstring date-time nullable

When the account's current billing period ends, or null when it has no active subscription with a renewal date.

created_atstring date-time
last_used_atstring date-time nullable
revoked_atstring date-time nullable
integration_warningstring

Present only for keys that belong to a Shopify, BigCommerce or WordPress Connect integration. The integration stops working until it reconnects with a new key.

Changes

No recorded changes to this operation across all 1 revision of this API.