Skip to navigation
DocumentationReferenceAPI ReferenceScoped Access Keys

Create Access Key

View as Markdown

Authentication

AuthorizationBearer
Supply a raw Helix access token. The Authorization header's Bearer prefix is added automatically.

Request

This endpoint expects an object.
namestring or nullOptional1-128 characters

Optional human-readable Scoped Access Key label. The token jti remains the stable identifier.

descriptionstring or nullOptional<=1024 characters

Optional human-readable description of the Scoped Access Key.

expires_in_secondsinteger or nullOptional>=1

Scoped Access Key lifetime in seconds. Omit to use auth.access_keys.default_expires_in_seconds. Send explicit null to request a non-time-delimited key, which requires auth.access_keys.max_expires_in_seconds to be disabled.

service_account_idstring or nullOptionalformat: "^[a-zA-Z0-9][a-zA-Z0-9._+/-]*$"1-240 characters

Optional non-human service account to bind the key to. Service-bound keys can only be created by a HelixAdmin and authenticate as service-account:<id>.

scopelist of strings or nullOptional
Optional service names that restrict this key to read and write access for those services.
rotatesstring or nullOptionalformat: "^ak_[0-9a-f]{32}$"

JTI of a prior Scoped Access Key owned by the caller to revoke after creation. Intended primarily for personal keys without a service-account identity.

workspaceslist of objects or nullOptional
Optional workspace memberships to grant to the newly created key principal.
service_attributesmap from strings to any or nullOptional

Facts a platform service vouches for, signed into the token under that service’s name in the nhx_service_attributes claim. Only a service principal, usually acting for a user, may set them. At most 32 names matching ^[A-Za-z][A-Za-z0-9_.-]63$, values nested at most one object or array deep, strings of at most 256 characters, and 2048 bytes as JSON.

Response

Successful Response
jtistring
Stable JWT ID for this Scoped Access Key.
principalstring
Principal ID stamped into the token.
statusenum
Allowed values:
issuerstring
Issuer stamped into the Scoped Access Key JWT.
audienceslist of strings
Audiences accepted for the Scoped Access Key JWT.
created_atdatetime
tokenstring
token_type"Bearer"
namestring or nullOptional

Optional human-readable Scoped Access Key label.

descriptionstring or nullOptional

Human-readable description of the Scoped Access Key.

entity_typeenumOptionalDefaults to USER

Whether the key is bound to a user or a non-human service account.

Allowed values:
scopelist of stringsOptional
Services this key is restricted to. An empty list means the key is unscoped.
expires_atdatetime or nullOptional
grace_period_expires_atdatetime or nullOptional

Timestamp when the rotated-out key’s grace period expires.

last_used_atdatetime or nullOptional
Timestamp of the most recent successful authentication with this Scoped Access Key.
service_attributesmap from strings to maps from strings to anyOptional

Attributes platform services signed into the key, by service name. Read-only to the key’s owner.

Errors

400
Bad Request Error
403
Forbidden Error
404
Not Found Error
409
Conflict Error
422
Unprocessable Entity Error
501
Not Implemented Error