Create API Key
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.
Internal session cookie for local development.
In: cookie
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
application/json
application/json
curl -X POST "https://example.com/api/v1/api-keys" \ -H "Content-Type: application/json" \ -d '{ "name": "My Documentation Key", "scopes": [ "user:read", "resume:read" ] }'{ "success": true, "message": "API key generated successfully. Please save it as it won't be shown again.", "data": { "id": "cmnu7awv4000063lk18zpon2m", "key": "vw_3f2a1c9e8b7d6f5a4c3b2a1908f7e6d5c4b3a29180706f5e4d3c2b1a09f8e7d6", "keyPrefix": "vw_3f2a1", "keySuffix": "09f8e7d6", "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-11T10:37:35.584Z", "updatedAt": "2026-04-11T10:37:35.584Z", "lastUsed": null }}Get API KeyGET
Returns the full metadata record for one of the caller's keys — name, scopes, rate limit, expiry, revocation state, and last-used timestamp. **The secret is not returned**, and cannot be: only an HMAC-SHA256 hash of it is stored. If you have lost a key's value, rotate it. `keyPrefix` and `keySuffix` are the only fragments kept, and neither is enough to reconstruct the key. Session-authenticated only — an API key cannot be used to manage API keys.
Rotate API KeyPOST
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`.