Credentials

Rotate an API key

Mint a successor with the same grant and return its secret once. The old key keeps working for overlap_seconds, then stops. The person rotating must cover the key's access (403 grant_forbidden, details.reason target_not_covered), and a key an owner created is rotated by an owner only (403 forbidden, details.reason owner_key_rotation), since rotating hands over the new secret. The Primitive CLI's token is refused, even with a step-up. Needs the organization's credential features to be enabled; while they are not, this answers 404 feature_disabled.

Person only: a dashboard session, or the person's own OAuth token with a step-up token for purpose keys.create in the Primitive-Step-Up header. Without one an OAuth token is answered 403 step_up_required, whose details carry the dashboard URL that issues it (or 403 grant_forbidden when the person's role could not do it anyway). The person's role must hold keys:manage. API keys and agent connection keys are refused. An agent acting for the person is refused unless it carries a step-up token the person issued in the dashboard.

post/keys/{id}/rotate

Request

  • Base URL
    https://api.primitive.dev/v1
  • URL
    https://api.primitive.dev/v1/keys/{id}/rotate
  • Auth
    HTTP bearer

Path parameters

idstring required

The id of the object this operation acts on.

Headers

Primitive-Step-Upstring

A single-use step-up token the person issued in the dashboard for this operation's purpose (valid five minutes). Needed only when calling with an OAuth token; a dashboard session does not send it. Accepted only with a token of the client it was confirmed for; refused with a token issued for MCP and with any API key.

Idempotency-Keystring

Optional client-supplied idempotency key. Retrying a request with the same key returns the original result instead of performing the action a second time; if omitted the server derives one from the canonical payload hash. Safe to retry network failures without duplicating side effects.

Request body

overlap_secondsinteger

Response

Success

successtrue required

Changes

No operation changes recorded.