Create a new API key

POST

/v1/api-keys

curl --request POST \
  --url https://api.aetherpush.com/v1/api-keys \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "name": "github-actions-ci", "scopes": [ "deploy", "read" ], "expires_at": "2026-12-31T23:59:59Z" }'

• Production
• Staging
• Local development

Creates a new API key with the given name and scopes. The response includes the raw key value in the key field. This is the only time the raw key is returned; store it securely.

The tenant’s max_api_keys quota applies — exceeding it returns 429.

Creating an API key requires a dashboard login session. Any other credential receives 403 with code dashboard_session_required.

An account that passed its two-factor setup deadline with MFA still off is refused here with 403 and code mfa_setup_required.

Authorizations

• accessKeyAuth

Request Body^required

Media typeapplication/json

object

name

required

string

>= 1 characters <= 100 characters

scopes

required

Array<string>

>= 1 items

Allowed values: deploy apps keys read

expires_at

Expiration date (ISO 8601). Must be in the future. Null means no expiration.

string | null format: date-time

Example

{
  "name": "github-actions-ci",
  "scopes": [
    "deploy",
    "read"
  ],
  "expires_at": "2026-12-31T23:59:59Z"
}

Responses

201

API key created. Raw key returned in key field.

Media typeapplication/json

Returned only by POST /v1/api-keys. The key field contains the raw secret and is shown exactly once — clients must store it securely. Subsequent reads of the key resource omit this field.

object

id

required

string format: uuid

name

required

string

key_prefix

required

string

scopes

required

Array<string>

Allowed values: deploy apps keys read

expires_at

required

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

key

required

The raw API key. Returned only on creation. Store securely.

string

Example

{
  "id": "5b3f1c8a-4d2e-4a7c-9a1b-8e6f3c2d1b0a",
  "name": "github-actions-ci",
  "key_prefix": "aether_sk_live_AbC123XyZ",
  "key": "aether_sk_live_AbC123XyZ4567abcdEFGHijkl",
  "scopes": [
    "deploy",
    "read"
  ],
  "expires_at": "2026-12-31T23:59:59Z",
  "revoked_at": null,
  "last_used_at": null,
  "created_at": "2025-04-30T10:00:00Z",
  "updated_at": "2025-04-30T10:00:00Z"
}

400

Missing/invalid name, scopes, or expires_at.

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

Refused. dashboard_session_required for any credential that is not a current dashboard login session, including an API key, named access key, CLI session or session without a recorded origin; mfa_setup_required when the account passed its two-factor setup deadline with MFA still off.

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"
}

429

Tenant API key quota exceeded.

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": "API key limit reached (25). Upgrade your plan for more keys.",
  "requestId": "req_abc123"
}