Skip to content
Synthetic Users

API keys

API keys authenticate non-dashboard callers (CI, custom scripts, integrations).

POST /api-keys

Terminal window
curl -s -X POST "$API_URL/api-keys" \
  -H "Authorization: Bearer $SYNTHUSERS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "ci-pipeline" }'

Response (plaintext returned once)

{
  "id": "key_01H...",
  "name": "ci-pipeline",
  "prefix": "sk_live_a1b2c3d4",
  "plaintext": "sk_live_a1b2c3d4e5f6...  ← copy this now, shown only once"
}

After this call, only the SHA-256 hash is retained on our side. The plaintext cannot be retrieved later. If lost, mint a new one.

You can mint keys from the dashboard too (/api-keys) — recommended for first-time setup.

GET /api-keys

{
  "items": [
    {
      "id": "key_01H...",
      "name": "ci-pipeline",
      "prefix": "sk_live_a1b2c3d4",
      "created_at": "2026-05-15T18:00:00Z",
      "last_used_at": "2026-05-15T19:24:00Z",
      "revoked_at": null
    }
  ]
}

DELETE /api-keys/:id

Revokes the key. The next request with that key returns 401 invalid_api_key. Revocation is immediate (KV is the hot-path lookup; the revocation row is purged within a few seconds).

Best practices

  • One key per environment (dev, staging, ci, prod).
  • One key per teammate if you need attribution. last_used_at tells you the last time we saw it on the wire.
  • Rotate keys quarterly (this is V1 hygiene — automation lands V1.5).
  • Never commit a key. The dashboard prefix is the only safe identifier to store in source.