Update an API key

PATCH

/v1/api-keys/{id}

curl --request PATCH \
  --url https://api.aetherpush.com/v1/api-keys/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0 \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "scopes": [ "deploy", "read", "apps" ] }'

• Production
• Staging
• Local development

Updates name, scopes, and/or expires_at on an existing API key. At least one field must be provided. Cannot update revoked keys.

Once the account passed its two-factor setup deadline with MFA still off, changing expires_at and widening the scope set are both refused with 403 and code mfa_setup_required. Renaming and narrowing scopes stay open.

Authorizations

• accessKeyAuth

Parameters

Path Parameters

id

required

string format: uuid

Request Body^required

Media typeapplication/json

Body shape for updating an API key. All fields optional. At least one field must be provided.

object

name

string

>= 1 characters <= 100 characters

scopes

Array<string>

>= 1 items

Allowed values: deploy apps keys read

expires_at

string | null format: date-time

Example

{
  "scopes": [
    "deploy",
    "read",
    "apps"
  ]
}

Responses

200

API key updated.

Media typeapplication/json

API key metadata. Fields use snake_case for historical reasons — this will be normalized to camelCase in a future API version.

object

id

required

string format: uuid

name

required

string

>= 1 characters <= 100 characters

key_prefix

required

Public, non-sensitive prefix for visual identification of the key. Format: aether_sk_live_ followed by 9 base62 characters.

string

scopes

required

Array<string>

>= 1 items

Allowed values: deploy apps keys read

expires_at

required

Null means no expiration.

string | null format: date-time

revoked_at

required

string | null format: date-time

last_used_at

required

string | null format: date-time

created_at

required

string format: date-time

updated_at

required

string format: date-time

Example

{
  "name": "github-actions-ci",
  "key_prefix": "aether_sk_live_AbC123XyZ",
  "scopes": [
    "deploy",
    "read"
  ]
}

400

Missing or invalid fields.

Media typeapplication/json

object

error

required

Human-readable error message.

string

requestId

Unique identifier for the request, also exposed as the X-Request-Id response header.

string

Example

{
  "error": "The requested resource was not found.",
  "requestId": "req_abc123"
}

401

Unauthenticated.

Media typeapplication/json

object

error

required

Human-readable error message.

string

requestId

Unique identifier for the request, also exposed as the X-Request-Id response header.

string

Example

{
  "error": "The requested resource was not found.",
  "requestId": "req_abc123"
}

403

API keys and named access keys receive a plain 403. A valid login session that is not a dashboard login session receives dashboard_session_required; an account that passed its two-factor setup deadline and asks to change expires_at or widen its scopes receives mfa_setup_required.

Media typeapplication/json

One of:

object

object

error

required

Human-readable error message.

string

requestId

Unique identifier for the request, also exposed as the X-Request-Id response header.

string

object

Returned when the account passed its two-factor setup deadline and asks for a new credential. Same shape as the reauth response so clients can branch on code rather than on message text.

object

error

required

string

code

required

string

Allowed values: mfa_setup_required

requestId

string

object

Returned after login-session validation when a valid session that is not a dashboard login session tries to issue or widen an API key, create an access key or change its lifetime, enrol a passkey or authenticator app, start a passkey step-up challenge, or run the CLI device ceremony. Endpoints that enforce both guards reject API keys and named access keys earlier with a plain 403 response and no code. API-key creation applies only the dashboard-session guard, so any non-dashboard credential receives this response there. Listing, renaming and revoking stay open to any login session. Sessions created before the credential_origin column existed cannot be attributed to the dashboard and are also refused; signing out and back in fixes that.

object

error

required

string

code

required

string

Allowed values: dashboard_session_required

requestId

string

Example

{
  "error": "The requested resource was not found.",
  "requestId": "req_abc123"
}

404

API key not found.

Media typeapplication/json

object

error

required

Human-readable error message.

string

requestId

Unique identifier for the request, also exposed as the X-Request-Id response header.

string

Example

{
  "error": "The requested resource was not found.",
  "requestId": "req_abc123"
}

409

Cannot update a revoked API key.

Media typeapplication/json

object

error

required

Human-readable error message.

string

requestId

Unique identifier for the request, also exposed as the X-Request-Id response header.

string

Example

{
  "error": "The requested resource was not found.",
  "requestId": "req_abc123"
}