Mint an API key
POST/v1/api_keys
Returns the token **once**; it is stored hashed and cannot be shown again.
A key can never grant a scope the key minting it does not itself hold — otherwise the ability to mint keys would be an escalation path to every permission on the account.
Set expires_in_days to rotate with an overlap window: mint the replacement, expire the old key, and both work until the window closes.
Body
| Field | Type | Description |
|---|---|---|
| namerequired | string | |
| mode | string | One of live, test. |
| scopesrequired | array of Scope | |
| allowed_cidrs | array of string | Restricts the key to these source blocks. |
| expires_in_days | integer |
Example
curl -X POST https://api.woyra.io/v1/api_keys \
-H "Authorization: Bearer $WOYRA_KEY" \
-H 'Content-Type: application/json' \
-d '{
"name": "<name>",
"scopes": []
}'Response
201 The key, including its token.
| Field | Type | Description |
|---|---|---|
| object | "api_key" | |
| id | string | |
| name | string | |
| mode | string | One of live, test. |
| prefix | string | The indexed, non-secret portion. Identifies a key in logs without being usable. |
| scopes | array of Scope | |
| created_at | timestamp | |
| last_used_at | timestamp | |
| expires_at | timestamp | |
| revoked_at | timestamp | |
| token | string | Present only in the response to creation. Store it now; it cannot be shown again. |
Errors
| Status | Codes |
|---|---|
| 400 | invalid_request, unsupported_version |
| 403 | insufficient_scope, domain_not_verified, recipient_suppressed, sending_paused, mfa_required |
Also in API keys
- GET /v1/api_keys — List API keys
- DELETE /v1/api_keys/{id} — Revoke an API key