Rotate API Key
Revokes the target key and issues a replacement in one transaction. The old secret stops working immediately. Every field in the body is optional — send `{}` to rotate the secret while carrying over the existing name, scopes, and rate limit. As with creation, the new secret is returned exactly once. The response also carries `rotatedFromId`, the id of the key that was replaced. Only an active, unrevoked key can be rotated; anything else returns `404`.
Internal session cookie for local development.
In: cookie
Path Parameters
The ID of the API key to rotate.
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
application/json
application/json
application/json
curl -X POST "https://example.com/api/v1/api-keys/string/rotate" \ -H "Content-Type: application/json" \ -d '{}'{ "success": true, "message": "API key rotated successfully. Please save the new key immediately.", "data": { "id": "cmnu7awv4000063lk18zpon2n", "key": "vw_9e8d7c6b5a4938271605f4e3d2c1b0a99887766554433221100ffeeddccbbaa9", "keyPrefix": "vw_9e8d7", "keySuffix": "ccbbaa9", "name": "My Documentation Key", "userId": "cmnu7awv4000063lk18zpon2x", "isActive": true, "rateLimit": 20, "scopes": [ "user:read", "resume:read" ], "expiresAt": "2027-04-11T10:37:35.584Z", "revokedAt": null, "createdAt": "2026-04-26T10:00:00.000Z", "updatedAt": "2026-04-26T10:00:00.000Z", "lastUsed": null, "rotatedFromId": "cmnu7awv4000063lk18zpon2m" }}Create API KeyPOST
Generates a new API key. **The full secret is returned exactly once, in this response.** It is stored only as an HMAC-SHA256 hash and can never be retrieved again — save it immediately. Session-authenticated only — an API key cannot be used to mint API keys.
Revoke API KeyPOST
Immediately disables an API key without deleting its record — `isActive` becomes false and `revokedAt` is stamped. The cached authentication record is purged at the same time, so the secret stops working right away rather than after the cache expires. A revoked key cannot be reactivated; rotate or create a new one instead. `data` is `null` on success.