Create a new API key

POST

/v1/api-keys

const url = 'https://api.aetherpush.com/v1/api-keys';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"name":"github-actions-ci","scopes":["deploy","read"],"expires_at":"2026-12-31T23:59:59Z"}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

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

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

application/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.

application/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

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.

application/json

Error

Standard error envelope. code is the stable machine identifier for client branching and i18n. The wording of error is a human-readable fallback and is not part of the contract. Specialized responses keep narrower code enums where clients already branch on them.

object

error

required

Human-readable error message.

string

code

required

Stable machine code. Prefer this over matching on error. The values this API can answer with are listed in the ApiErrorCode schema of the raw document at https://api.aetherpush.com/openapi.yaml. The field stays an open string here so that a release adding a value does not invalidate this response.

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.",
  "code": "not_found",
  "requestId": "req_abc123"
}

401

Unauthenticated.

application/json

Error

object

error

required

Human-readable error message.

string

code

required

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.",
  "code": "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.

application/json

Any of:

Error

object

error

required

Human-readable error message.

string

code

required

string

requestId

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

string

MfaSetupRequiredError

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

DashboardSessionRequiredError

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, run the CLI device ceremony, change the password, or request or cancel the account’s deletion. Endpoints that enforce both guards reject API keys and named access keys earlier with a plain 403 carrying code: session_required. 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.",
  "code": "not_found",
  "requestId": "req_abc123"
}

429

Two causes share this status. The tenant limiter answers RateLimitErrorResponse (error, retryAfterSeconds) with Retry-After. The tenant API key quota answers the Error envelope and no Retry-After.

application/json

One of:

RateLimitError
Error

RateLimitError

Returned with HTTP 429 when an endpoint-specific rate limit is hit, including the per-tenant management API budget. Not the process-wide address limiter (see GlobalAddressRateLimitErrorResponse). retryAfterSeconds indicates how long the client should wait before retrying, and matches the Retry-After header when that header is set. code names the limit that fired so clients can translate without matching on error.

object

error

required

string

code

required

string

retryAfterSeconds

required

integer

>= 1

requestId

string

Error

object

error

required

Human-readable error message.

string

code

required

string

requestId

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

string

Examples

Tenant management budget spent

{
  "error": "Rate limit exceeded",
  "code": "tenant_rate_limit_exceeded",
  "retryAfterSeconds": 60
}

Tenant API key quota exceeded

{
  "error": "API key limit reached (25). Upgrade your plan for more keys.",
  "code": "api_key_limit_reached",
  "requestId": "req_abc123"
}

Headers

Retry-After

integer

>= 1

Present only for the tenant limiter.

Create a new API key

Authorizations

Request Bodyrequired

Example

Responses

201

Example

400

Example

401

Example

403

Example

429

Examples

Headers

Request Body^required