SynqDocs
Management APIAPI keys

Rotate an API key

A new key with the key's name, permissions, brand roles and IP allowlist, `sk_live_…` in production, `sk_test_…` elsewhere, in this response only. The key rotated keeps working for `overlap_seconds` beside it, as a rotated app secret does, so whatever uses it can switch first: its `expires_at` becomes the end of the overlap (never later than it was) and its `replaced_by` names the new key; after that it answers 401 `api_key_rotated`. When the key had an expiry, the new one's is as far from now as the key's was from its making. A key is rotated once: a revoked, expired or rotated one answers 409 `conflict`, and the next rotation is its replacement's, which ends an earlier key still in its overlap with the new overlap at the latest. Needs `org.apiKeys.edit` across the org, or in each brand the key works in, and everything the key holds, as making it does: a key for All brands is the owner's to rotate (`all_brands_owner_only`). A person needs a sign-in at Synq from the last 5 minutes whose time Synq proved (send them to sign in with `max_age=300`), else 403 `fresh_sign_in_required`; an API key never does. Recorded as `api_key.rotated`, and the old key's end as `api_key.expired` when it comes.

POST/v1/orgs/{org}/api-keys/{key}/rotate

A new key with the key's name, permissions, brand roles and IP allowlist, sk_live_… in production, sk_test_… elsewhere, in this response only. The key rotated keeps working for overlap_seconds beside it, as a rotated app secret does, so whatever uses it can switch first: its expires_at becomes the end of the overlap (never later than it was) and its replaced_by names the new key; after that it answers 401 api_key_rotated. When the key had an expiry, the new one's is as far from now as the key's was from its making. A key is rotated once: a revoked, expired or rotated one answers 409 conflict, and the next rotation is its replacement's, which ends an earlier key still in its overlap with the new overlap at the latest. Needs org.apiKeys.edit across the org, or in each brand the key works in, and everything the key holds, as making it does: a key for All brands is the owner's to rotate (all_brands_owner_only). A person needs a sign-in at Synq from the last 5 minutes whose time Synq proved (send them to sign in with max_age=300), else 403 fresh_sign_in_required; an API key never does. Recorded as api_key.rotated, and the old key's end as api_key.expired when it comes.

Authorization

bearer
AuthorizationBearer <token>

An org API key (sk_live_…, sk_test_…), or an access token from the Synq issuer (the synq brand, on the accounts host) for this API.

In: header

Path Parameters

org*string

The org's id

Match^org_[0-9a-hjkmnp-tv-z]{26}$
key*string

The API key's id, never the key itself

Match^key_[0-9a-hjkmnp-tv-z]{26}$

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/problem+json

application/problem+json

application/problem+json

application/problem+json

application/problem+json

application/problem+json

curl -X POST "https://api.synq.build/v1/orgs/org_01h455vb4pex5vsknk084sn02q/api-keys/key_01h455vb4pex5vsknk084sn02q/rotate" \  -H "Authorization: Bearer $SYNQ_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "overlap_seconds": 86400  }'
{  "id": "key_01h455vb4pex5vsknk084sn02q",  "name": "Acme",  "prefix": "sk_live_Ab3d",  "permissions": [    "string"  ],  "brand_roles": [    {      "brand": "string",      "role": "string",      "permissions": [        "string"      ]    }  ],  "ip_allowlist": [    "string"  ],  "expires_at": "2026-10-21T12:00:00.000Z",  "revoked_at": "2026-10-21T12:00:00.000Z",  "last_used_at": "2026-10-21T12:00:00.000Z",  "created_by": "string",  "created_at": "2026-10-21T12:00:00.000Z",  "replaced_by": "key_01h455vb4pex5vsknk084sn02q",  "replaces": "key_01h455vb4pex5vsknk084sn02q",  "key": "string"}