Skip to content
AetherAether Docs

Create a new access key

POST
/v1/access-keys
curl --request POST \
  --url https://api.aetherpush.com/v1/access-keys \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "friendlyName": "ci-deploy-key", "ttl": 5184000000 }'

Creates a new access key on the current account. The response contains the raw key string in the name field. This is the only time the raw key is returned; store it securely.

If friendlyName collides with an existing key on the account, the request returns 409.

Creating an access key requires a dashboard login session. API keys and named access keys are refused earlier by the login-session requirement, with a plain 403 and no code. A valid CLI session or a session that predates credential attribution is refused with 403 and code dashboard_session_required, so a stolen session cannot mint a sibling that survives its own revocation. The raw key value is always server-generated; a body carrying name is refused with 400.

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

Authorizations

Section titled “Authorizations”

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json

Body shape for creating or updating an access key. On create, friendlyName is required. On update, all fields are optional; only provided fields are modified.

The raw key value is always generated by the server. A create request carrying a name field is refused with 400. createdBy is not part of the request: the server records it from the request IP, so a body still carrying it is not schema-valid, and the server ignores the value rather than refusing the request.

object
friendlyName

Human-friendly identifier for the key.

string
>= 1 characters <= 255 characters
description

Mirrors friendlyName. Kept for legacy clients.

string
ttl

Time-to-live in milliseconds. If omitted, the key expires in 60 days.

integer format: int64
>= 1
Example
{
  "friendlyName": "ci-deploy-key",
  "ttl": 5184000000
}

Responses

Section titled “Responses”

201

Section titled “201”

Access key created. Raw key returned in name.

Media typeapplication/json
object
accessKey
required
object
name

The raw key string. Only returned in full on POST /v1/access-keys (creation). On GET /v1/access-keys it is masked as (hidden). On GET /v1/access-keys/{name} it is omitted entirely.

string
friendlyName

Human-friendly identifier for the key.

string
<= 255 characters
description

Mirrors friendlyName. Kept for legacy clients.

string
createdBy

IP address that created the key.

string
createdTime

Unix timestamp in milliseconds.

integer format: int64
expires
required

Unix timestamp in milliseconds.

integer format: int64
isSession

True if the key was created by a login flow (vs. CLI/manual creation).

boolean
credentialOrigin

How the credential was created. Absent on credentials that predate CLI browser login. cli_browser and cli_device credentials are the ones listed and revoked through /v1/cli/devices.

string
Allowed values: dashboard_session cli_browser cli_device
deviceId

Stable identifier the CLI generates once per machine.

string
deviceName

Human-facing device label shown on the approval screen.

string
clientName

Client that requested the credential.

string
clientVersion

Client version at the time of authorization.

string
clientPlatform

Operating system and architecture reported by the client.

string
Example
{
  "accessKey": {
    "name": "abc123-base64url-secret",
    "friendlyName": "ci-deploy-key",
    "description": "ci-deploy-key",
    "createdBy": "203.0.113.42",
    "createdTime": 1714867200000,
    "expires": 1720051200000
  }
}

Headers

Section titled “Headers”
Location
string

Resource location of the newly created key.

400

Section titled “400”

Missing or invalid fields.

Media typeapplication/json
One of:
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

Section titled “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

Section titled “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 past its two-factor setup deadline receives mfa_setup_required.

Media typeapplication/json
One of:

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": "Issuing or widening an API key requires a dashboard login session.",
  "code": "dashboard_session_required"
}

409

Section titled “409”

A key with that friendlyName already exists.

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