API Keys

Base path: https://gateway.useyona.com/a/v1/organizations/:orgId/api-keys

API keys authenticate all requests to the Yona API. Each key is scoped to an environment — sandbox keys (sk_test_*) for development, production keys (sk_live_*) for live submissions.

Create API key

POST /a/v1/organizations/:orgId/api-keys

Create a new API key. The raw key is returned only once in this response.

Request body

Field	Type	Required	Description
`mode`	string	Yes	`sandbox` or `production`
`name`	string	No	Human-readable name
`expiresAt`	string	No	ISO date — key expiry
`rateLimit`	object	No	`{ requestsPerMinute?, dailyQuota? }`

bash

curl -X POST https://gateway.useyona.com/a/v1/organizations/9f8e7d6c-5b4a-3210-fedc-ba9876543210/api-keys \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "sandbox",
    "name": "Development API Key"
  }'

🚨 Store the key immediately

The key field is returned only once. It cannot be retrieved again after this response.

List API keys

GET /a/v1/organizations/:orgId/api-keys

bash

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

Revoke API key

PATCH /a/v1/organizations/:orgId/api-keys/:id/revoke

Revoke an API key. This is irreversible.

bash

curl -X PATCH https://gateway.useyona.com/a/v1/organizations/9f8e7d6c-5b4a-3210-fedc-ba9876543210/api-keys/7a8b9c0d-1e2f-3456-7890-abcdef123456/revoke \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Rotate API key

POST /a/v1/organizations/:orgId/api-keys/:id/rotate

Generate a new key and deprecate the old one with a grace period.

bash

curl -X POST https://gateway.useyona.com/a/v1/organizations/9f8e7d6c-5b4a-3210-fedc-ba9876543210/api-keys/7a8b9c0d-1e2f-3456-7890-abcdef123456/rotate \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Other API key endpoints

Method	Path	Description
`GET`	`/a/v1/organizations/:orgId/api-keys/:id`	Get API key details
`PATCH`	`/a/v1/organizations/:orgId/api-keys/:id/role`	Update key role
`GET`	`/a/v1/organizations/:orgId/api-keys/:id/permissions`	Get key permissions