---
title: "Replace a credential atomically without expanding its authority"
method: POST
path: "/account-credentials/{credentialId}/rotate"
tags: ["Account credentials"]
---

# Replace a credential atomically without expanding its authority

`POST /account-credentials/{credentialId}/rotate`

## Request

- Base URL: `https://app.communicate.so/api/v1`
- URL: `https://app.communicate.so/api/v1/account-credentials/{credentialId}/rotate`
- Auth: one of:
  - HTTP bearer
  - API key in cookie `__Secure-better-auth.session_token`
  - API key in cookie `better-auth.session_token`

Use an explicit credentials:write account bearer grant or a live email-verified application session, plus the current account password as fresh identity proof. Cookie writes require a trusted Origin. Machine callers cannot issue scopes beyond their own grant or outlive it. Creation and rotation return the secret once; metadata never includes it. Scope and expiry can only be narrowed. Issued credentials expire within 24 hours and no later than their issuer session; session revocation invalidates them.

## Path parameters

- `credentialId` string, uuid, required

## Headers

- `Origin` string, uri

## Request body

- AccountCredentialProof
  - `password` string, password, required

## Response `201`

Replace a credential atomically without expanding its authority

- AccountCredentialReceipt
  - `id` string, uuid, required
  - `name` string, required
  - `prefix` string, required
  - `scopes` string[], required
  - `expiresAt` string, date-time, required
  - `token` string, required: One-time credential secret; not present in subsequent metadata reads.

## Other responses

- `400`: Invalid request body or pagination.
- `401`: Session or credential missing, invalid, expired or revoked; fresh password proof failed when required.
- `403`: Email verification, trusted origin or required account scope is missing.
- `404`: Credential not found in the authenticated user account.
- `409`: Credential is inactive, already rotated, or requested scopes or expiry exceed its existing authority.
- `429`: Per-user list or password proof rate limit exceeded.
- `500`: Unexpected server failure.
- `503`: Identity service or freshly issued session unavailable.

---

[API](https://skmtc.dev/communicate/apis/communicate-public-rest-api-2.md) · [All operations](https://skmtc.dev/communicate/apis/communicate-public-rest-api-2/llms.txt) · [OpenAPI document](https://skmtc.dev/communicate/apis/communicate-public-rest-api-2/revisions/db6be3d36733?raw)