Auth
Read the signed-in profile, and create, list, and revoke secret API keys. Keys are account keys (rymi_acct_) or workspace keys (rymi_ws_), each with a scope list. See API keys and scopes.
Self-serve Rymi does not expose a public business-verification API. Phone numbers are BYOC, so carrier onboarding, identity checks, number provisioning, taxes, and regulatory documentation stay with the connected telephony provider.
Current profile
Returns profile state for the authenticated user. This route needs no key scope.
Example request
curl https://api.rymi.live/v1/auth/me \
-H "Authorization: Bearer $RYMI_API_KEY"Response 200
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"display_name": "Ada Lovelace",
"timezone": "America/New_York",
"locale": "en-US",
"api_key_prefix": "rymi_acct_a1B2c3",
"telephony_provider": "twilio",
"plivo_connected": false,
"business_name": "Acme Inc.",
"business_type": "restaurant"
}Describe this key
Returns the secret key on this request. SDKs and MCP call it once per connection. It needs no scope. A signed-in session with no secret key receives 401.
Response 200
{
"kind": "workspace",
"account_id": "3f1c0a2e-6b4d-4e1a-9c77-2a6e0b9d4f11",
"workspace_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"scopes": ["calls:write", "agents:read"],
"legacy": false
}| Field | Type | Description |
|---|---|---|
kind | string | account or workspace. |
account_id | string or null | Account the key belongs to. |
workspace_id | string or null | Set for a workspace key. null for an account key. |
scopes | string[] | Scopes on the key. Empty when legacy is true and the key predates scopes. |
legacy | boolean | true for an existing rymi_ key. Rymi treats it as an account key with every scope. |
Example
curl https://api.rymi.live/v1/keys/self \
-H "Authorization: Bearer $RYMI_API_KEY"const self = await rymi.keys.self();self = rymi.keys.self()Errors
| Status | Code | When |
|---|---|---|
| 401 | The caller is not a secret key. The error is Invalid API key. |
List API keys
Active (non-revoked) secret keys you may manage. A workspace Admin sees workspace keys for the current workspace. An account Owner or Admin also sees the account's keys, including legacy keys. Each row includes kind, scopes, and legacy. A key needs keys:read.
The Node and Python SDKs create and describe a key (keys.create, keys.self). Listing stays on this route.
Response 200
{
"keys": [
{
"id": "d1e2f3a4-b5c6-7890-abcd-ef1234567890",
"key_prefix": "rymi_acct_a1B2c3",
"label": "Production",
"last_used_at": "2026-10-09T10:15:22Z",
"created_at": "2026-10-01T09:00:00Z",
"kind": "account",
"scopes": ["calls:write", "agents:read", "billing:read"],
"legacy": false
},
{
"id": "a5b6c7d8-e9f0-1234-abcd-ef1234567890",
"key_prefix": "rymi_ws_a1B2c3d4",
"label": "Website calls",
"last_used_at": null,
"created_at": "2026-10-08T13:22:40Z",
"kind": "workspace",
"scopes": ["calls:write", "agents:read"],
"legacy": false
}
]
}| Field | Type | Description |
|---|---|---|
id | string | Key id. Send this to revoke. |
key_prefix | string | First 16 characters of the secret. |
label | string or null | Label from create, or null. |
last_used_at | string or null | Last successful authentication, or null. |
created_at | string | When the key was created. |
kind | string | account or workspace. A legacy key is account. |
scopes | string[] | Scopes granted at creation. |
legacy | boolean | true for a key created before scopes. Studio labels it Full access (legacy). |
key is returned only by create. Rymi stores a SHA-256 hash.
Example
curl https://api.rymi.live/v1/auth/api-keys \
-H "Authorization: Bearer $RYMI_API_KEY"const res = await fetch("https://api.rymi.live/v1/auth/api-keys", {
headers: { Authorization: `Bearer ${process.env.RYMI_API_KEY}` },
});
const { keys } = await res.json();import os
import requests
res = requests.get(
"https://api.rymi.live/v1/auth/api-keys",
headers={"Authorization": f"Bearer {os.environ['RYMI_API_KEY']}"},
)
keys = res.json()["keys"]Errors
| Status | Code | When |
|---|---|---|
| 401 | Missing authentication context. | |
| 403 | A publishable key. The error is Publishable keys cannot manage secret keys. | |
| 403 | role_forbidden | You are not a workspace Admin, and not an account Owner or Admin. |
| 403 | scope_missing | The key lacks keys:read. |
| 500 | The key list could not be read. |
Create API key
Creates a secret API key. The plaintext is the field key, returned once. An account key starts with rymi_acct_. A workspace key starts with rymi_ws_. A key needs keys:write.
An account key needs an account Owner or Admin, and a signed-in person: a secret key cannot create an account key. A workspace key needs a workspace Admin, or an account Owner or Admin, and it belongs to the current workspace. Scopes must be known strings. A workspace key can hold workspace scopes only. A key can grant a scope it holds. See the scope list and presets.
Body
| Field | Type | Required | Description |
|---|---|---|---|
kind | string | Yes | account or workspace. |
scopes | string[] | Yes | Scopes for this key. |
label | string | No | Up to 100 characters. Stored trimmed, or null when blank. |
Example
curl -X POST https://api.rymi.live/v1/auth/api-keys \
-H "Authorization: Bearer $RYMI_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "label": "Website calls", "kind": "workspace", "scopes": ["calls:write", "agents:read"] }'const created = await rymi.keys.create({
kind: "workspace",
label: "Website calls",
scopes: ["calls:write", "agents:read"],
});
// created.key is shown oncecreated = rymi.keys.create(
kind="workspace",
scopes=["calls:write", "agents:read"],
label="Website calls",
)
# created["key"] is shown onceResponse 201
{
"id": "a5b6c7d8-e9f0-1234-abcd-ef1234567890",
"key": "rymi_ws_a1B2c3d4e5F6g7H8i9J0kLmN",
"key_prefix": "rymi_ws_a1B2c3d4",
"kind": "workspace",
"scopes": ["calls:write", "agents:read"],
"label": "Website calls",
"created_at": "2026-10-09T14:30:00Z"
}WARNING
key is shown once. The field name is key. If you lose it, revoke the key and create another.
Errors
| Status | Code | When |
|---|---|---|
| 400 | kind is not account or workspace. | |
| 400 | invalid_scope | scopes is not a list of strings (scope is null), or a scope is unknown for that kind. scope names the first bad one, for example billing:read on a workspace key. |
| 401 | Missing authentication context. | |
| 403 | A publishable key. | |
| 403 | role_forbidden | The caller cannot create that kind, an Editor tried, a secret key tried to create an account key, or a key tried to grant a scope it does not hold. |
| 403 | scope_missing | The key lacks keys:write. |
| 500 | The key could not be stored. |
Revoke API key
Sets revoked_at; the key stops working on its next request. Live calls in the workspace you revoke it from end, because the voice gateway cannot tell which calls a secret key started. A key needs keys:write. A workspace key can be revoked from its workspace by someone who manages workspace keys. An account key can be revoked by an account Owner or Admin.
Path parameters
| Field | Type | Required | Description |
|---|---|---|---|
id | string | Yes | Key id from the list. |
Example
curl -X DELETE https://api.rymi.live/v1/auth/api-keys/a5b6c7d8-e9f0-1234-abcd-ef1234567890 \
-H "Authorization: Bearer $RYMI_API_KEY"const res = await fetch(
"https://api.rymi.live/v1/auth/api-keys/a5b6c7d8-e9f0-1234-abcd-ef1234567890",
{ method: "DELETE", headers: { Authorization: `Bearer ${process.env.RYMI_API_KEY}` } },
);
const body = await res.json();import os
import requests
res = requests.delete(
"https://api.rymi.live/v1/auth/api-keys/a5b6c7d8-e9f0-1234-abcd-ef1234567890",
headers={"Authorization": f"Bearer {os.environ['RYMI_API_KEY']}"},
)
body = res.json()Response 200
{ "success": true }Errors
| Status | Code | When |
|---|---|---|
| 401 | Missing authentication context. | |
| 403 | A publishable key. | |
| 403 | role_forbidden | You cannot manage keys in this workspace. |
| 403 | scope_missing | The key lacks keys:write. |
| 404 | The id is unknown, already revoked, or it belongs to a workspace or account you cannot manage. The error is API key not found or already revoked. |
Billing writes
Secret keys, including legacy rymi_ keys, can no longer call billing writes. Each returns 403 scope_missing with required_scope set to null:
POST /v1/billing/checkout/startPOST /v1/billing/mandate/registerPOST /v1/billing/reconcilePUT /v1/billing/auto-rechargePUT /v1/billing/extra-usagePUT /v1/billing/alertsPUT /v1/billing/countryDELETE /v1/billing/payment-methods/:id
Billing reads need billing:read. To add credits, top up in Studio under Account → Billing.
Rotation
- Create a key with a label such as
Production 2026-Q4. - Deploy
keyeverywhere the old key is used. - Confirm
last_used_aton the new row. - Revoke the old key.
Both keys work until you revoke the old one.
Legacy: regenerate secret API key
Deprecated
This endpoint replaces the account's single legacy key immediately. Any service using the old key fails until you update it. Prefer POST /v1/auth/api-keys and DELETE /v1/auth/api-keys/:id. Sign in to call it; API keys get 403.
Response 200
{ "api_key": "rymi_new_secret_key_xxxxxxxx" }This response field is api_key. Create (POST /v1/auth/api-keys) returns key.
Errors
| Status | Meaning |
|---|---|
401 | Missing or invalid authentication. This is the response that signs a person out of Studio. |
403 scope_missing | The key lacks the route's scope. The body is { "error": "Missing scope", "code": "scope_missing", "required_scope": "calls:write" }. required_scope is null for a billing write. |
403 role_forbidden | The caller's role cannot manage keys. |
404 | Key id not found, already revoked, or outside the workspaces you manage. |
500 | Server error. |

