Roll an API key
Issues a new secret for a secret key, keeping its id, name, permissions and expiry, and returns it in rawKey, shown only this once.
The previous secret stops working at once, or after overlapSeconds. Only a person signed in to the Voidhash dashboard can do this; a secret key, a CLI key or an MCP client cannot.
Guide: API keys
A project secret key: vh_sk_... for production, vh_sk_test_... for test. Keep it on your servers.
In: header
Path parameters
The project's id, proj_.... A secret key works only in the project it belongs to.
The key's id: api_sk_... for a secret key, api_pk_... for a publishable key.
Request body
application/json
TypeScript definitions
Use the request body type in TypeScript.
Seconds the previous secret keeps working so deployments can switch over, up to 604,800 (7 days). Omit to stop it at once.
Examples
curl -X POST "https://api.voidhash.com/api/v1/projects/proj_tz4a98xxat96iws9zmbrgj3a/api-keys/api_sk_r6t9y2u5i8o1p4a7s0d3f6g9/rotate" \ -H "Authorization: Bearer vh_sk_..." \ -H "Content-Type: application/json" \ -d '{ "overlapSeconds": 3600 }'{ "id": "api_sk_r6t9y2u5i8o1p4a7s0d3f6g9", "projectId": "proj_tz4a98xxat96iws9zmbrgj3a", "name": "Production backend", "type": "secret", "environment": "production", "prefix": "vh_sk_", "end": "9LpX", "rawKey": "vh_sk_...9LpX", "scopes": [ "project:read", "project:persons:write", "project:entitlements:read" ], "expiresAt": null, "lastUsedAt": "2026-03-14T09:26:00.000Z", "previousKeyExpiresAt": "2026-03-14T10:30:00.000Z", "createdAt": "2026-02-01T08:00:00.000Z"}{ "error": { "type": "invalid_request", "code": "publishable_key_not_editable", "message": "A publishable key cannot be edited, rotated or deleted: your apps ship with it. Only secret keys can.", "param": "apiKeyId" }}{ "error": { "type": "unauthenticated", "code": "invalid_api_key", "message": "This secret key is not valid." }}{ "error": { "type": "permission_denied", "code": "permission_denied", "message": "Insufficient permissions." }}{ "error": { "type": "not_found", "code": "project_not_found", "message": "There is no project proj_tz4a98xxat96iws9zmbrgj3a, or this credential cannot use it.", "param": "projectId" }}{ "error": { "type": "internal", "code": "internal_error", "message": "Something went wrong on our side. Try again, and contact support with the Request-Id header if it keeps failing." }}Response body
application/json
application/json
application/json
application/json
application/json
application/json
Errors
| Status | type | code | When |
|---|---|---|---|
| 400 | invalid_request | publishable_key_not_editable | For a publishable key. |
It can also fail with the errors every operation shares, such as unauthenticated; see Errors.
More in API keys
- List API keys
GET - Create an API key
POST - Retrieve an API key
GET - Update an API key
PATCH - Delete an API key
DELETE
Something wrong or missing on this page? Tell us by email or on Discord.