Skip to content
Yagra

Every issued personal access token, as metadata.

GET
/api/v1/api-tokens
curl --request GET \
  --url https://example.com/api/v1/api-tokens \
  --header 'Authorization: Bearer <token>'

Neither the raw token nor its hash is returned — a token’s value exists only in the response that created it. These credentials authenticate whichever surfaces each token names — /mcp, this REST API, or both.

Authorizations

Section titled “Authorizations”

Responses

Section titled “Responses”

200

Section titled “200”

Token metadata only — never the raw token or its hash

Media typeapplication/json
Array<object>

One API token’s metadata for the admin listing — never the raw token or its hash. A credential is not returned in an API response after it has been issued.

object
created_at
required
string format: date-time
created_by
required
string
expires_at

When the token stops authenticating, or None for no expiry.

string | null format: date-time
id
required
string format: uuid
last_used_at
string | null format: date-time
name
required
string
owner

The account the token acts as. None means the owner was deleted before this column existed, or could not be matched during the 0057 backfill — such a token no longer authenticates and is shown so an admin can revoke it deliberately.

string | null
owner_active
required

Whether the owner account is currently able to authenticate (enabled). Surfaced so the listing can explain a token that is live by its own dates yet refused.

boolean
owner_idle_days

How many days the owner may go without signing in before this token stops authenticating. Set only when the owner authenticates through an external IdP (SSO or LDAP), because an identity provider does not tell Yagra when it disables an account; None for local and service accounts, whose tokens do not expire on idleness.

integer | null format: int64
owner_last_login_at

The owner’s last interactive sign-in, when the owner authenticates through an external IdP. This is the only signal Yagra has that an SSO account is still live (see [ApiTokenStore]), so the listing shows it; None for local and service accounts, where it means nothing.

string | null format: date-time
revoked_at
string | null format: date-time
role
required

Predefined roles, ordered least → most privileged.

string
Allowed values: viewer operator admin
scope
required
One of:

Unrestricted visibility.

string
Allowed values: All
surfaces
required

Which auth surfaces this token may be presented at. Never empty in practice — a token that named no surface could authenticate nowhere — but stored as a list so it can grow.

Array<string>
Allowed values: mcp rest
Example
[
  {
    "role": "viewer",
    "scope": "All",
    "surfaces": [
      "mcp"
    ]
  }
]

401

Section titled “401”

No valid bearer token

Media typeapplication/json

The ADR-019 envelope every failure renders as. pub(crate) and schema-bearing so the OpenAPI document can name one error shape for every endpoint (ADR-035) instead of leaving 4xx/5xx bodies undescribed — a client that has to guess the failure shape ends up parsing the success shape and reading undefined.

object
error
required
object
code
required

Stable machine-readable code. Clients branch on this, never on the message.

string
message
required

Operator-facing sentence. Safe to display; never carries an internal error’s own text.

string
Examplegenerated
{
  "error": {
    "code": "example",
    "message": "example"
  }
}

403

Section titled “403”

Role below Admin

Media typeapplication/json

The ADR-019 envelope every failure renders as. pub(crate) and schema-bearing so the OpenAPI document can name one error shape for every endpoint (ADR-035) instead of leaving 4xx/5xx bodies undescribed — a client that has to guess the failure shape ends up parsing the success shape and reading undefined.

object
error
required
object
code
required

Stable machine-readable code. Clients branch on this, never on the message.

string
message
required

Operator-facing sentence. Safe to display; never carries an internal error’s own text.

string
Examplegenerated
{
  "error": {
    "code": "example",
    "message": "example"
  }
}

503

Section titled “503”

Skeleton mode has no token store

Media typeapplication/json

The ADR-019 envelope every failure renders as. pub(crate) and schema-bearing so the OpenAPI document can name one error shape for every endpoint (ADR-035) instead of leaving 4xx/5xx bodies undescribed — a client that has to guess the failure shape ends up parsing the success shape and reading undefined.

object
error
required
object
code
required

Stable machine-readable code. Clients branch on this, never on the message.

string
message
required

Operator-facing sentence. Safe to display; never carries an internal error’s own text.

string
Examplegenerated
{
  "error": {
    "code": "example",
    "message": "example"
  }
}