Auth

Account-scoped endpoints for reading profile state and managing secret API keys.

Rymi supports multiple labeled secret API keys per account so you can:

• Keep separate keys for dev, staging, and production.
• Rotate keys with zero downtime. Create a new key, deploy it, revoke the old one.
• Give a contractor or third-party service a dedicated key and revoke only that one.

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 account.

Example Request

curl https://api.rymi.live/v1/auth/me \
  -H "Authorization: Bearer YOUR_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_...",
  "telephony_provider": "twilio",
  "plivo_connected": false,
  "business_name": "Acme Inc.",
  "business_type": "restaurant"
}

---

List API Keys

GET/v1/auth/api-keys

Returns all active (non-revoked) secret API keys for the authenticated account.

Example Request

curl https://api.rymi.live/v1/auth/api-keys \
  -H "Authorization: Bearer YOUR_API_KEY"

Response 200

{
  "keys": [
    {
      "id": "d1e2f3a4-...",
      "key_prefix": "rymi_abcd1",
      "label": "Production",
      "last_used_at": "2026-04-23T10:15:22Z",
      "created_at": "2026-04-01T09:00:00Z"
    },
    {
      "id": "a5b6c7d8-...",
      "key_prefix": "rymi_wxyz9",
      "label": "Staging",
      "last_used_at": null,
      "created_at": "2026-04-20T13:22:40Z"
    }
  ]
}

The raw api_key is only ever returned at creation time. Rymi stores it as a SHA-256 hash and never returns it again.

---

Create API Key

POST/v1/auth/api-keys

Creates a secret API key. The plaintext key is returned once, so save it immediately.

Body

Field	Type	Required	Description
label	string	no	Human-readable label (e.g. "Production", "CI"). Max 100 chars.

Example Request

curl -X POST https://api.rymi.live/v1/auth/api-keys \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"label": "Production"}'

Response 201

{
  "id": "d1e2f3a4-...",
  "api_key": "rymi_abcd1XYZ-full-secret-key-here",
  "key_prefix": "rymi_abcd1",
  "label": "Production",
  "created_at": "2026-04-23T14:30:00Z"
}

WARNING

api_key is shown once and cannot be retrieved again. If you lose it, revoke the key and create a new one.

---

Revoke API Key

DELETE/v1/auth/api-keys/{id}

Soft-deletes the key (sets revoked_at). Any active WebSocket sessions authenticated with this specific key are terminated via a broadcast event; sessions using other keys are unaffected.

Example Request

curl -X DELETE https://api.rymi.live/v1/auth/api-keys/d1e2f3a4-... \
  -H "Authorization: Bearer YOUR_API_KEY"

Response 200

{ "success": true }

---

Rotation pattern (zero downtime)

Rotate a key in four steps:

1. Create a new key with a descriptive label ("Production 2026-Q2").
2. Deploy the new key to all environments that use the old one.
3. Verify traffic is flowing on the new key (check last_used_at on the list endpoint).
4. Revoke the old key.

At no point does production traffic break, because both keys are valid simultaneously.

---

Legacy: Regenerate Secret API Key

POST/v1/auth/regenerate-key

Deprecated

This endpoint still works for backward compatibility, but it replaces the account's single legacy key immediately. Any service using the old key fails until you update it. Prefer the multi-key endpoints above (POST /v1/auth/api-keys + DELETE /v1/auth/api-keys/{id}) so you can rotate without downtime.

Response 200

{ "api_key": "rymi_new_secret_key_xxxxxxxx" }

---

Errors

Status	Meaning
401	Missing or invalid authentication
403	Attempting to manage secret keys using a publishable key
404	Key ID not found or already revoked
500	Server error