Skip to content

api_keys

API keys: the credential a machine uses to call the API.

An API key belongs to one user account and acts as that account, with a permission set narrowed to the key's scopes. It is created from a signed-in session, shown in full exactly once, and stops authenticating on the expiry date chosen at creation or when it is deleted.

API_KEY_PREFIX = 'ysk_' module-attribute

Every API key starts with this; the server recognises a key by it.

UNSCOPEABLE_RESOURCES = frozenset({'user', 'api_key'}) module-attribute

Permission resources a key can never carry, whatever the server allows.

Managing the account and managing keys stay with a signed-in person, so a leaked key cannot change a password, accept legal documents, buy credits or mint further keys. What a key MAY carry is the server's decision: it serves the vocabulary with a key_scopeable flag per permission (GET /status/permissions), and a client offers scopes from that, never from a list of its own.

ApiKeyCreate pydantic-model

Bases: BaseModel

Request to create an API key on the signed-in account.

Fields:

Validators:

  • _scopes_are_scopeable

description = None pydantic-field

What the key is for and what holds it, for the account's own records: a device, a system, an integration.

expires_in_days = None pydantic-field

Days until the key expires, at most the server's maximum. Omitted means the server's default lifetime. Every key expires; rotate by creating the next key before this one lapses.

name pydantic-field

A label for telling keys apart, such as the system that will hold it.

password pydantic-field

The account password, entered again: creating a long-lived credential is confirmed by the person, not only by their session.

scopes pydantic-field

The permissions the key may exercise. A key never holds more than its owner holds at the time of a request, and cannot be scoped to account (user:*) or key (api_key:*) management. The server reports which permissions may be delegated (GET /status/permissions, key_scopeable) and refuses any other.

ApiKeyCreated pydantic-model

Bases: ApiKeyOut

The response to creating a key: the listing fields plus the secret.

Fields:

secret pydantic-field

The full key. It appears only in this response; store it in a secret manager now. Send it as Authorization: Bearer <key>.

ApiKeyOut pydantic-model

Bases: BaseModel

An API key as listed on the account: everything except the secret.

Config:

  • from_attributes: True

Fields:

description = None pydantic-field

What the key is for and what holds it.

expired pydantic-field

Whether the key has passed its expiry. An expired key no longer authenticates; delete it and create a new one.

expires_at pydantic-field

When the key stops authenticating requests.

last_used_at = None pydantic-field

When the key last authenticated a request, recorded to the hour; null if it never has.

prefix pydantic-field

The first characters of the key, for telling keys apart in a list or a log. Never enough to use the key.

scopes pydantic-field

The permissions the key was created with.

scopeable_permissions(vocabulary)

Return the permissions a key may be scoped to, in the served order.

vocabulary is what GET /status/permissions returned; the account and key resources are excluded even if a server were to flag them.