---
title: "Roll a secret"
method: POST
path: "/api/v1/account/credentials/roll"
tags: ["Credentials"]
---

# Roll a secret

`POST /api/v1/account/credentials/roll`

## Request

- Base URL: `https://api.sahha.ai` (the document declares no server; this is the origin it was published from)
- URL: `https://api.sahha.ai/api/v1/account/credentials/roll`
- Auth: API key in header `Authorization`

Creates a new secret for the account's application or client credential in the given environment and returns it once. The secret it replaces keeps working until expireOldIn has passed: 7 days by default for a client secret, until it is revoked for an app secret, so shipped apps keep working until they are updated. A credential holds at most two active secrets, so a third roll is refused until one is revoked or has expired. The caller must be a member of the account, signed in with a user token.

## Query parameters

- `environment` string

## Request body

- RollCredentialSecretRequest
  - `accountId` string, uuid: The account the credential belongs to.
  - `environment` string: sandbox or production. It must be the environment the request is sent to.
  - `credentialType` string: application or client.
  - `expireOldIn` string, nullable: How long the secret being replaced keeps working: immediate, 24h, 7d, 30d or untilRevoked. Defaults to 7d for a client secret and untilRevoked for an app secret. Ignored when the credential has no secret yet.

## Response `200`

The new secret and every secret of the credential.

- RollCredentialSecretResponse
  - `secret` string: The new secret. It is shown once and cannot be retrieved again; store it now.
  - `secretId` string, uuid: The new secret's id, as listed in secrets.
  - `secrets` CredentialSecretDto[]: Every secret of the credential after the roll, including the one being replaced and its expiry.
    - `id` string, uuid: The secret's id, used to revoke or restore it.
    - `credentialType` string: application or client.
    - `isLegacy` boolean: True for a secret issued before rotation launched. Its value stays readable on the credential while it can authenticate.
    - `status` string: active, expired or revoked.
    - `hint` string, nullable: The secret's prefix and last four characters, such as sahha_app_prod_...Ab3x, enough to tell secrets apart and to confirm a revoke. A legacy secret's hint is its last four characters alone.
    - `createdAt` string, date-time
    - `expiresAt` string, date-time, nullable: When the secret stops authenticating. Null while it has no expiry.
    - `revokedAt` string, date-time, nullable
    - `restoredAt` string, date-time, nullable
    - `lastUsedAt` string, date-time, nullable: The last time the secret authenticated, to within five minutes.

## Other responses

- `400`: The request isn't valid, or its environment isn't the one it was sent to.
- `401`: Not signed in.
- `403`: Not a member of the account.
- `404`: The account has no such credential in the environment.
- `409`: Two secrets are already active.
- `429`: Too many credential changes by this user.

---

[API](https://skmtc.dev/sahha/apis/sahha-platform-v1.md) - [All operations](https://skmtc.dev/sahha/apis/sahha-platform-v1/llms.txt) - [OpenAPI document](https://skmtc.dev/sahha/apis/sahha-platform-v1/revisions/c7f918b46707?raw)