Skip to content

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 ​

GET/v1/auth/me

Returns profile state for the authenticated user. This route needs no key scope.

Example request ​

bash
curl https://api.rymi.live/v1/auth/me \
  -H "Authorization: Bearer $RYMI_API_KEY"

Response 200 ​

json
{
  "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 ​

GET/v1/keys/self

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 ​

json
{
  "kind": "workspace",
  "account_id": "3f1c0a2e-6b4d-4e1a-9c77-2a6e0b9d4f11",
  "workspace_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "scopes": ["calls:write", "agents:read"],
  "legacy": false
}
FieldTypeDescription
kindstringaccount or workspace.
account_idstring or nullAccount the key belongs to.
workspace_idstring or nullSet for a workspace key. null for an account key.
scopesstring[]Scopes on the key. Empty when legacy is true and the key predates scopes.
legacybooleantrue for an existing rymi_ key. Rymi treats it as an account key with every scope.

Example ​

bash
curl https://api.rymi.live/v1/keys/self \
  -H "Authorization: Bearer $RYMI_API_KEY"
ts
const self = await rymi.keys.self();
python
self = rymi.keys.self()

Errors ​

StatusCodeWhen
401The caller is not a secret key. The error is Invalid API key.

List API keys ​

GET/v1/auth/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 ​

json
{
  "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
    }
  ]
}
FieldTypeDescription
idstringKey id. Send this to revoke.
key_prefixstringFirst 16 characters of the secret.
labelstring or nullLabel from create, or null.
last_used_atstring or nullLast successful authentication, or null.
created_atstringWhen the key was created.
kindstringaccount or workspace. A legacy key is account.
scopesstring[]Scopes granted at creation.
legacybooleantrue 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 ​

bash
curl https://api.rymi.live/v1/auth/api-keys \
  -H "Authorization: Bearer $RYMI_API_KEY"
ts
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();
python
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 ​

StatusCodeWhen
401Missing authentication context.
403A publishable key. The error is Publishable keys cannot manage secret keys.
403role_forbiddenYou are not a workspace Admin, and not an account Owner or Admin.
403scope_missingThe key lacks keys:read.
500The key list could not be read.

Create API key ​

POST/v1/auth/api-keys

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 ​

FieldTypeRequiredDescription
kindstringYesaccount or workspace.
scopesstring[]YesScopes for this key.
labelstringNoUp to 100 characters. Stored trimmed, or null when blank.

Example ​

bash
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"] }'
ts
const created = await rymi.keys.create({
  kind: "workspace",
  label: "Website calls",
  scopes: ["calls:write", "agents:read"],
});
// created.key is shown once
python
created = rymi.keys.create(
    kind="workspace",
    scopes=["calls:write", "agents:read"],
    label="Website calls",
)
# created["key"] is shown once

Response 201 ​

json
{
  "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 ​

StatusCodeWhen
400kind is not account or workspace.
400invalid_scopescopes 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.
401Missing authentication context.
403A publishable key.
403role_forbiddenThe 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.
403scope_missingThe key lacks keys:write.
500The key could not be stored.

Revoke API key ​

DELETE/v1/auth/api-keys/:id

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 ​

FieldTypeRequiredDescription
idstringYesKey id from the list.

Example ​

bash
curl -X DELETE https://api.rymi.live/v1/auth/api-keys/a5b6c7d8-e9f0-1234-abcd-ef1234567890 \
  -H "Authorization: Bearer $RYMI_API_KEY"
ts
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();
python
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 ​

json
{ "success": true }

Errors ​

StatusCodeWhen
401Missing authentication context.
403A publishable key.
403role_forbiddenYou cannot manage keys in this workspace.
403scope_missingThe key lacks keys:write.
404The 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/start
  • POST /v1/billing/mandate/register
  • POST /v1/billing/reconcile
  • PUT /v1/billing/auto-recharge
  • PUT /v1/billing/extra-usage
  • PUT /v1/billing/alerts
  • PUT /v1/billing/country
  • DELETE /v1/billing/payment-methods/:id

Billing reads need billing:read. To add credits, top up in Studio under Account → Billing.


Rotation ​

  1. Create a key with a label such as Production 2026-Q4.
  2. Deploy key everywhere the old key is used.
  3. Confirm last_used_at on the new row.
  4. Revoke the old key.

Both keys work until you revoke the old one.


Legacy: regenerate secret API key ​

POST/v1/auth/regenerate-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 ​

json
{ "api_key": "rymi_new_secret_key_xxxxxxxx" }

This response field is api_key. Create (POST /v1/auth/api-keys) returns key.


Errors ​

StatusMeaning
401Missing or invalid authentication. This is the response that signs a person out of Studio.
403 scope_missingThe 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_forbiddenThe caller's role cannot manage keys.
404Key id not found, already revoked, or outside the workspaces you manage.
500Server error.