API keys

List API keys

GET /a/v1/organizations/{orgId}/api-keys

A page of the organisation’s API keys in every status. Metadata only, never a secret.

Who can call it: Signed-in user only: do this in the Yona app.

Parameters

Example request

curl https://gp.useyona.com/a/v1/organizations/me/api-keys \
  -H "Authorization: Bearer YOUR_SESSION_TOKEN"

Responses

Create an API key

POST /a/v1/organizations/{orgId}/api-keys

Creates a sandbox or live key with a preset or an explicit list of capabilities (the read_only preset when neither is given). A live key also needs the live_mode.use capability. The response is the key’s metadata plus key, the full secret (sk_test_… or sk_live_…): it is shown in this response only and cannot be retrieved again.

Who can call it: Signed-in user only: do this in the Yona app.

Parameters

Request body

Example request

curl -X POST https://gp.useyona.com/a/v1/organizations/me/api-keys \
  -H "Authorization: Bearer YOUR_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "ERP integration",
    "mode": "sandbox"
  }'

Responses

The key’s metadata and its plaintext key, shown once.

Get an API key

GET /a/v1/organizations/{orgId}/api-keys/{id}

One API key’s metadata, never its secret.

Who can call it: Signed-in user only: do this in the Yona app.

Parameters

Example request

curl https://gp.useyona.com/a/v1/organizations/me/api-keys/9f8e7d6c-5b4a-3210-fedc-ba9876543210 \
  -H "Authorization: Bearer YOUR_SESSION_TOKEN"

Responses

Rename an API key

PATCH /a/v1/organizations/{orgId}/api-keys/{id}

Changes the key’s name only. Capabilities change through PUT …/api-keys/{id}/capabilities.

Who can call it: Signed-in user only: do this in the Yona app.

Parameters

Request body

Example request

curl -X PATCH https://gp.useyona.com/a/v1/organizations/me/api-keys/9f8e7d6c-5b4a-3210-fedc-ba9876543210 \
  -H "Authorization: Bearer YOUR_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "string"
  }'

Responses

Replace an API key’s capabilities

PUT /a/v1/organizations/{orgId}/api-keys/{id}/capabilities

The new list replaces the old one and may only name capabilities the caller holds. Access tokens already issued to the key stop working.

Who can call it: Signed-in user only: do this in the Yona app.

Parameters

Request body

Example request

curl -X PUT https://gp.useyona.com/a/v1/organizations/me/api-keys/9f8e7d6c-5b4a-3210-fedc-ba9876543210/capabilities \
  -H "Authorization: Bearer YOUR_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "capabilities": [
      "organization.read"
    ]
  }'

Responses

Get an API key’s capabilities

GET /a/v1/organizations/{orgId}/api-keys/{id}/permissions

What the key may do now, and which capabilities the caller could grant it.

Who can call it: Signed-in user only: do this in the Yona app.

Parameters

Example request

curl https://gp.useyona.com/a/v1/organizations/me/api-keys/9f8e7d6c-5b4a-3210-fedc-ba9876543210/permissions \
  -H "Authorization: Bearer YOUR_SESSION_TOKEN"

Responses

Revoke an API key

PATCH /a/v1/organizations/{orgId}/api-keys/{id}/revoke

The key stops working at once.

Who can call it: Signed-in user only: do this in the Yona app.

Parameters

Example request

curl -X PATCH https://gp.useyona.com/a/v1/organizations/me/api-keys/9f8e7d6c-5b4a-3210-fedc-ba9876543210/revoke \
  -H "Authorization: Bearer YOUR_SESSION_TOKEN"

Responses

Rotate an API key

POST /a/v1/organizations/{orgId}/api-keys/{id}/rotate

Issues a new key with the same name, mode, capabilities and expiry. The old key keeps working for the grace period (gracePeriodSeconds) and is then retired. A live key also needs the live_mode.use capability, and the caller must hold every capability of the key. The new key’s full secret is returned once, in current.key.

Who can call it: Signed-in user only: do this in the Yona app.

Parameters

Request body

Example request

curl -X POST https://gp.useyona.com/a/v1/organizations/me/api-keys/9f8e7d6c-5b4a-3210-fedc-ba9876543210/rotate \
  -H "Authorization: Bearer YOUR_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "gracePeriodSeconds": 1
  }'

Responses

The old key (previous, now rotating) and the new key (current) with its plaintext key, shown once.