aethexDocs
Dashboard

API Reference

API Keys API

Manage the API keys your application uses to call Aethex.Who can do what. Any key can list your tenant's keys with GET /api-keys and rotate itself with POST /api-keys/{key_id}/rotate; the new key keeps the old key's expiry. Rotating any other key is key management and needs the api_keys:write scope, which keys you create yourself never carry — so rotate, create and revoke your other keys in the developer portal (Dashboard → API Keys), which calls the session-authenticated routes at /api/v1/dashboard/api-keys.Keys issued by the Aethex platform. On a workspace the Aethex platform manages, its Settings → API Keys page issues and rotates the keys: there a key without api_keys:write sees only itself in GET /api-keys and rotates nothing, itself included.Authentication. Send your existing API key as X-API-Key: ae_live_… (or Authorization: Bearer ae_live_…). Rotating returns the new key value exactly once — store it before the response goes out of scope.

Base URL
https://api.aethexai.com/api/v1
Endpoints
2
GET/api-keys

Return your tenant's API keys. Response is a bare JSON array (not paginated).

List API Keys

Returns the tenant's active and revoked API keys, newest first (the developer portal's own internal key is never listed). On a workspace the Aethex platform manages, a key without api_keys:write gets a one-element array instead: that key itself, with its scopes, rate limits, expiry and usage. The response is a bare JSON array — there is no envelope and no pagination — so plan for the whole list on every call.The key field is always null on this endpoint; the raw secret is only ever returned on creation or rotation. key_prefix (the first 12 characters of the original key, e.g. ae_live_ebc5) is what lets you correlate a row here with a key stored in your secret manager.

Errors

1
401Unauthorized

Missing or invalid API key.

Send X-API-Key: '<'api_key'>' or Authorization: Bearer '<'api_key'>'.

POST/api-keys/:key_id/rotate

Mint a new secret for a live key, keeping its name, scopes and limits. A key can rotate itself; the old secret keeps working for a 24-hour grace period by default.

Rotate an API Key

Issues a new secret for a live key while preserving its name, rate limits and scopes (any operator-only scope is dropped). The plaintext key is returned in the key field exactly once — store it immediately.The old secret keeps working for a 24-hour grace period, or until its own expiry if that comes sooner (old_key_expires_at carries the time); during that window both secrets authenticate so callers can roll out the new value without downtime. Pass ?revoke_immediately=true to hard-revoke the old secret in the same call (use for suspected compromise) — old_key_expires_at is null in that case.Who can rotate. A key can rotate itself, and the new key expires when the old one would have: at the old key's own expiry, or at the end of the grace period an earlier rotation gave it. A key without an expiry gets a new key without one. Rotating any other key needs the api_keys:write scope: the calling key may only rotate a key whose rate limits and scopes it holds itself (operator-only scopes are dropped from the new key, not compared), and cannot rotate any key that holds api_keys:write, itself included. On a workspace the Aethex platform manages, no key rotates itself: rotate keys from the platform's Settings → API Keys. A revoked or expired key cannot be rotated by anyone: create a new key instead.

Path & Query

2
  • key_idstring (uuid)required

    ID of the API key to rotate. Use the id field from GET /api-keys, not the key_prefix.

  • revoke_immediatelybooleanoptional

    When false (default), the old key keeps working for a 24-hour grace period (never past its own expiry); the grace expiry is returned as old_key_expires_at. Set to true to hard-revoke the old key in the same call.

Errors

4
401Unauthorized

Missing or invalid API key.

Send X-API-Key: '<'api_key'>' or Authorization: Bearer '<'api_key'>'.

403Not allowed to rotate this key

The calling key does not hold api_keys:write (Missing scope) and is rotating another key, or any key on a workspace the Aethex platform manages; or the key being rotated has rate limits, or scopes other than operator-only ones, that the calling key does not hold.

Rotate a key with that key itself, or in the developer portal (Dashboard → API Keys). On a workspace the Aethex platform manages, use the platform's Settings → API Keys.

404Key not found

No API key with the supplied key_id exists on your tenant.

Check the id against GET /api-keys.

409Key cannot be rotated

The key has been revoked or has expired, or it holds api_keys:write itself. Or a key holding api_keys:write is rotating another key with a grace period while the workspace already has 25 active keys.

Create a new key in place of a revoked or expired one. A key that holds api_keys:write cannot be rotated through this route. At the 25-key limit, revoke a key first or pass ?revoke_immediately=true.