API Keys

Create an API key (returns the plaintext once)

Changed on

Returns the new key's plaintext secret, which is shown only in this response, with its id, prefix, organization id, and any permissions or budget. With permissions enabled, only a signed-in session creates keys, and a new key belongs to the organization (kind org), so it keeps working if its creator leaves; personal and service kinds are refused, except dashboard playground keys, which are always personal. Its permissions come from template or permissions and can never exceed the creator's own access (403 ESCALATION_REFUSED). scopes still works and maps to the key's ceiling. budget caps what the new key may spend on inference per period. A key that carries a budget cannot create keys (403 FORBIDDEN), so it cannot mint itself one without a budget.

Checked against the apikey.create permission for the resource it acts on. See Permissions for the roles and API key permissions that include it.

post/v1/orgs/{orgId}/api-keys/create

Request

  • Base URL
    https://api.openrelay.inc
  • URL
    https://api.openrelay.inc/v1/orgs/{orgId}/api-keys/create
  • Auth
    HTTP bearer

Path parameters

orgIdstring required

Request body

ephemeralboolean

Dashboard use only: a short-lived personal key for the playground and batch pages, limited to Inference, Batch Read and Batch Write (each held by the creator), expiring within 900 seconds and never listed.

expiresInSecondsinteger

Optional server-side expiry, in seconds from now. When set (and > 0) the key stops authenticating after this many seconds, capping the leak window regardless of any client-side cleanup. Omitted or <= 0 means the key never expires (the default).

kind'personal' | 'org'

Permissions enabled only. org (the default) belongs to the organization and keeps working if its creator leaves. personal is refused for non-ephemeral creates.

namestring required
notestring

Permissions enabled only. Where the key is used; shown when someone revokes it.

permissionsstring[]

Permissions enabled only. The key's permission ceiling, as permission ids.

scopesstring[]

Supported values: clusters:read, clusters:write, vms:read, vms:write, inference, and inference:endpoint:<id> for an enabled dedicated endpoint owned by the organization. An endpoint scope also adds the inference scope when it is omitted. clusters:read grants read access to the organization's resources, including VMs and pods, and clusters:write grants write access, including VM restart and API key creation. vms:read and vms:write are accepted for compatibility but grant nothing on their own, so each must be requested together with clusters:read or clusters:write respectively; a request with one but not the other returns 400. With permissions enabled, a session's request with scopes creates an organization key whose ceiling the scopes map to.

serviceAccountIdstring

No longer supported. Requests containing this field are refused.

templatestring

Permissions enabled only. A key template id from GET /v1/authz/catalog (inference, inference_batch, compute_automation, read_only). Ignored when permissions is set.

Response

Created

cedarstring

The Cedar policies generated for the key's restrictions.

createdAtstring required
expiresAtstring
idstring required
keystring required

Plaintext key, shown once

keyPrefixstring required
kind'personal' | 'org' | 'legacy'
namestring required
organizationIdstring required

The organization this key is bound to. Every API key belongs to exactly one organization; keep this id alongside the key so callers can build org-scoped request paths without a separate lookup (GET /v1/whoami returns the same id for an existing key).

ownerUserIdstring
permissionsstring[]
scopesstring[] required

Changes

  • 7fe59d94a9f5Revision changes
    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

  • 551a288b9aa0Revision changes
    • breaking

      removed the enum value service of the request property

    • warning

      removed the optional property from the response with the status

    • info

      request property deprecated

    • info

      removed the service enum value from the response property for the response status