API keys

API-key management is itself an authenticated API. You can use it from the dashboard or via the REST endpoints below.

List your keys

curl https://api.openphn.com/auth/api_keys \
  -H "Authorization: Bearer $OPENPHN_KEY"

The response includes each key's id, name, prefix (first 16 chars only — the secret is not stored), scopes, number_ids, created_at, and last_used_at. The secret is never returned on list.

Create a key

curl -X POST https://api.openphn.com/auth/api_keys \
  -H "Authorization: Bearer $OPENPHN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name":       "prod-batch-caller",
    "scopes":     ["calls:create", "calls:read"],
    "number_ids": ["num_abcd1234"],
    "expires_at": "2027-04-21T00:00:00Z"
  }'

• name — required. Used only for display in the dashboard.
• scopes — optional. Omit for a full-permission key. See Authentication for the list.
• number_ids — optional. Restricts the key to specific numbers.
• expires_at — optional. ISO-8601. Key is rejected after this time.

Response:

{
  "id":     "key_01HV...",
  "secret": "sk_live_AbC123...XyZ789",
  "prefix": "sk_live_AbC123..",
  "name":   "prod-batch-caller"
}

Rotate a key

curl -X POST https://api.openphn.com/auth/api_keys/key_01HV.../rotate \
  -H "Authorization: Bearer $OPENPHN_KEY"

Behavior:

1. A new secret is returned. Deploy it immediately.
2. The old key keeps working for 24h (the grace period) so in-flight clients can migrate.
3. Every use of the old key during grace is audit-logged with a rotated_key_used event — investigate and update any stragglers.
4. After the grace period, the old key is revoked.

Revoke a key

curl -X DELETE https://api.openphn.com/auth/api_keys/key_01HV... \
  -H "Authorization: Bearer $OPENPHN_KEY"

Immediate effect — no grace period. Use this if a key leaks.

whoami

curl https://api.openphn.com/auth/me \
  -H "Authorization: Bearer $OPENPHN_KEY"

Returns the user + tenant the key belongs to, the key's scopes and number_ids, and verification status. Handy for sanity-checking env vars.