Manage your API keys

Tenants can list, create, rotate, and revoke their own API keys without contacting us. All four endpoints live under /v1/api-keys and are authenticated with the same X-API-Key header you already use.

Safety rails

• Plaintext is shown only once. When a new key is minted (create or rotate), the api_key field is in the response body and never returned again.
• Lockout protection. Revoking a key that is your last active key returns 409 Conflict. Create a new one first, then revoke the old.
• Audit log. Every create / rotate / revoke is recorded with the tenant ID, key prefix, and originating API key.

List your keys

curl https://api.cloudtalknet.com/v1/api-keys \
  -H "X-API-Key: $CLOUDTALK_API_KEY"

{
  "tenant_id": "ten_abc...",
  "items": [
    {
      "id": "key_2YqkX...",
      "label": "production",
      "api_key_prefix": "msk_live_a1b2c3",
      "created_at": "2026-04-12T09:33:21Z",
      "revoked_at": null,
      "is_active": true
    }
  ]
}

The plaintext key is never returned here — only the prefix (first ~12 chars) so you can recognise which entry corresponds to a key sitting in your secret store.

Create a new key

Issue an additional key — useful for staging vs production, or as the first half of a zero-downtime rotation.

curl -X POST https://api.cloudtalknet.com/v1/api-keys \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $CLOUDTALK_API_KEY" \
  -d '{ "label": "mobile-backend" }'

{
  "id": "key_5LpqR...",
  "tenant_id": "ten_abc...",
  "label": "mobile-backend",
  "api_key": "msk_live_a1b2c3...VERY_LONG...",
  "api_key_prefix": "msk_live_a1b2c3",
  "created_at": "2026-05-08T14:02:11Z"
}

Save api_key immediately — this is the only response that contains the plaintext. We don't store the plaintext, only a SHA-256 hash.

Rotate a key

Atomic replace: the old key is revoked and a new plaintext is returned in the same response. Update your client config before any further request — the old key stops working immediately.

curl -X POST https://api.cloudtalknet.com/v1/api-keys/key_2YqkX.../rotate \
  -H "X-API-Key: $CLOUDTALK_API_KEY"

{
  "tenant_id": "ten_abc...",
  "revoked_api_key_id": "key_2YqkX...",
  "new_api_key_id": "key_8FrtM...",
  "api_key": "msk_live_z9y8x7...VERY_LONG...",
  "api_key_prefix": "msk_live_z9y8x7"
}

If you rotate the same key you used to authenticate the request, the response is the last call you can make with that token. Make sure you've captured the new api_key before the next request.

Revoke a key

curl -X POST https://api.cloudtalknet.com/v1/api-keys/key_8FrtM.../revoke \
  -H "X-API-Key: $CLOUDTALK_API_KEY"

Recommended rotation pattern

Zero-downtime rotation in three steps:

sequenceDiagram
    participant You as Your Backend
    participant CTN as CloudTalk Networks
    You->>CTN: POST /v1/api-keys (label="rotation-2026-05")
    CTN-->>You: { api_key: "msk_live_NEW...", id: "key_NEW" }
    Note over You: Roll new key into config and redeploy
    You->>CTN: POST /v1/api-keys/{old_id}/revoke (with NEW key)
    CTN-->>You: { revoked_api_key_id: "key_OLD" }

Steps:

1. Create a new key (using your current key).
2. Deploy your services with the new key.
3. Revoke the old key (using the new key) once all instances are using the new one.

This pattern means you never have a window where requests can fail because of a missing key.