API DashboardAPI pricing

API reference

Rotate API key

Rotate a scoped API key secret. Review Diffio API behavior, response fields, setup details, and production workflows.

Replace a scoped API key secret and return the new plaintext key once.

POST/v1/api_keys/rotatePermissions: admin, keys:write

Endpoint

HTTP request

https://api.diffio.ai/v1/api_keys/rotate

Use POST with a JSON body.

Permissions

admin, keys:write

API keys must be active.

Authentication

Send the API key on every request using one of the supported headers.

  • Authorization: Bearer <apiKey>
  • X-Api-Key: <apiKey>
  • Xi-Api-Key: <apiKey>

Request

Provide the target scoped key id.

Body fields

FieldTypeRequiredDescription
keyIdstringYesScoped API key id to rotate.
cURL
curl -X POST "https://api.diffio.ai/v1/api_keys/rotate" \  -H "Authorization: Bearer $DIFFIO_AGENT_KEY" \  -H "Content-Type: application/json" \  -d '{    "keyId": "key_child_123"  }'

Response

Returns updated key metadata plus the new plaintext key once.

Response fields

FieldTypeRequiredDescription
keystringYesNew plaintext API key secret. It is returned only in this response.
keyIdstringYesRotated API key id.
statusstringYesKey status after rotation.
keyPrefixstringYesNew display-safe key prefix.
rotatedAtstringYesRotation timestamp in ISO 8601 format.
Successful response
{  "key": "diffio_live_rotated_secret",  "keyId": "key_child_123",  "label": "Dashboard browser key",  "status": "active",  "keyPrefix": "diffio_live_rotat",  "role": "scoped",  "scopes": ["projects:read", "generations:read"],  "resourceBounds": {},  "parentKeyId": "key_admin_123",  "createdAt": "2026-05-09T12:00:00Z",  "rotatedAt": "2026-05-09T12:30:00Z",  "revokedAt": null}

Return codes

  • 200Success, treated as complete.: Scoped API key rotated.
  • 204Success, treated as empty response.: CORS preflight when method is OPTIONS.
  • 400Bad request, treated as client error.: Invalid JSON body, or keyId is required.
  • 401Unauthorized, treated as auth error.: Missing API key, or invalid API key.
  • 403Forbidden, treated as permission error.: Privileged admin API key required, API key is not active, missing keys:write permission, or target key is an admin key.
  • 404Not found, treated as missing resource.: API key not found.
  • 405Client error, treated as fix required.: Method is not POST.
  • 500Server error, treated as retryable.: Failed to rotate API key.

Notes

  • Admin keys cannot be rotated through this public API endpoint.
  • The previous key secret stops authenticating after a successful rotation.
  • The endpoint writes an audit log entry for successful rotation.