Skip to content
Hayonix

API reference · API keys

Create an API key (the secret is returned once)

POST/v1/api-keys
Console sessionapi_key:createProjectIdempotency-Key

Creates a key that acts inside this project with the scopes you give it, which may not exceed what your own role grants. The secret appears only in this response and cannot be read again; a replay with the same Idempotency-Key returns the same response.

Console session only: no API key can be granted the api_key:create permission it needs. Requires the api_key:create permission (a key's scope, or a role that includes it).

Request

Headers
HeaderRequiredDescription
X-Project-IdyesThe project to act in, for console sessions. Requests with an API key leave it out.
Idempotency-KeynoMakes a retry safe: the same key and request within 24 hours return the original response (see Idempotency). The SDKs send one for you.

Body

JSON (application/json): CreateApiKeyRequest.

  • namestringrequired

    Its name

    1–100 characters

  • scopesarray of stringrequired

    Actions (`resource:verb`) or `resource:*`; at most your own role grants

    1–100 items

  • expires_atstring (date-time) | null

    When it expires (null: never) (ISO 8601, UTC)

Response

201 CreatedApiKey — The new key, including its secret

  • objectstringrequired

    Always `api_key`: the type of this object

    One ofapi_key

  • idstringrequired

    Unique ID (`key_…`)

    ID with prefix key_

  • org_idstringrequired

    Organization it belongs to

    ID with prefix org_

  • project_idstringrequired

    Project it belongs to

    ID with prefix prj_

  • namestringrequired

    Its name

  • scopesarray of stringrequired

    Actions (`resource:verb` or `resource:*`) the key may perform, as granted

  • last4stringrequired

    Last four characters of the secret, for display

  • statusstringrequired

    `active`: usable; `revoked`: revoked and refused from then on; `expired`: past `expires_at` and refused

    One ofactiverevokedexpired

  • expires_atstring (date-time) | nullrequired

    When it expires (null: never) (ISO 8601, UTC)

  • last_used_atstring (date-time) | nullrequired

    Updated at most once a minute

  • revoked_atstring (date-time) | nullrequired

    When it was revoked (null while it is valid) (ISO 8601, UTC)

  • created_by_user_idstring | nullrequired

    ID of the user who created it

  • created_byobject | nullrequired

    Who created it (null: created by the platform)

    Show 3 fields of created_by
    • objectstringrequired

      Always `person`

      One ofperson

    • idstringrequired

      The person’s user ID (`usr_…`)

    • namestring | nullrequired

      Their name as they set it; null when they are no longer a member of the organization

  • created_atstring (date-time)required

    When it was created (ISO 8601, UTC)

  • updated_atstring (date-time)required

    When it last changed (ISO 8601, UTC)

  • secretstringrequired

    The API key. Returned only in this response; store it now.

Example response
Example response
{
  "object": "api_key",
  "id": "key_01jc5zq4m8k3v6x9t2w7r0b1e4",
  "org_id": "org_01jc5zq4m8k3v6x9t2w7r0b1e4",
  "project_id": "prj_01jc5zq4m8k3v6x9t2w7r0b1e4",
  "name": "string",
  "scopes": [
    "ssh_key:read",
    "inference:invoke"
  ],
  "last4": "string",
  "status": "active",
  "expires_at": "2026-01-01T00:00:00.000Z",
  "last_used_at": "2026-01-01T00:00:00.000Z",
  "revoked_at": "2026-01-01T00:00:00.000Z",
  "created_by_user_id": "string",
  "created_by": {
    "object": "person",
    "id": "string",
    "name": "string"
  },
  "created_at": "2026-01-01T00:00:00.000Z",
  "updated_at": "2026-01-01T00:00:00.000Z",
  "secret": "sk_01jc5zq4m8k3v6x9t2w7r0b1e4_…"
}

Errors

Errors use the standard envelope. What this operation can answer:

Errors
StatusTypeWhen
400invalid_request_errorA parameter or body field is missing or not allowed; param names it.
401authentication_errorThe key or session is missing, revoked or expired.
403permission_errorThe credential lacks the permission this needs, or the organization is suspended.
409conflict_error idempotency_in_progressA request with the same Idempotency-Key is still running.
422idempotency_error idempotency_key_reusedThe Idempotency-Key was used with a different request.
429rate_limit_error rate_limitedToo many requests; retry after retry-after seconds.