formdata.dev

Key Rotation

POST /v1/admin/keys/rotate revokes all existing tenant keys for the organization and issues a new one.

Immediate Revocation

Key rotation is immediate. All previous keys (sk_ prefix) stop working as soon as the rotation completes. Update your integrations before rotating.

Rotate Key

Request

POST /v1/admin/keys/rotate x-tenant-key: sk_live_abc123...

No request body is required.

Example

curl -X POST https://api.formdata.dev/v1/admin/keys/rotate \
  -H "x-tenant-key: sk_live_abc123..."

Response (200)

{
  "ok": true,
  "tenantKey": "sk_live_newkey456..."
}
Field Description
tenantKey The new secret key. Save it immediately — it cannot be retrieved later.

Errors

Status Error Cause
401 Missing x-tenant-key Header not provided
401 Invalid tenant key Key is revoked or does not exist

How It Works

  1. All rows in organization_api_keys for the organization have their revoked_at set to the current timestamp
  2. A new key is generated, hashed with SHA-256, and inserted
  3. The new plaintext key is returned in the response

:::tip Key Prefixes

  • sk_ — Secret tenant key for admin API authentication
  • pk_ — Public form key for the ingestion endpoint (not affected by key rotation) :::
ON THIS PAGE