---
title: "Rotate Widget Embed Credential"
method: POST
path: "/v1/widgets/embed-credentials/{id}/rotate"
tags: ["Widgets"]
---

# Rotate Widget Embed Credential

`POST /v1/widgets/embed-credentials/{id}/rotate`

## Request

- Base URL: `https://api.sandbox.usenash.com`
- URL: `https://api.sandbox.usenash.com/v1/widgets/embed-credentials/{id}/rotate`
- Auth: none declared

Issue a replacement credential and retire the outgoing one. With `overlap_minutes > 0` both work until the window closes; with `0` the outgoing credential is revoked immediately.

## Path parameters

- `id` string, required: The Nash widget embed credential id (``wec_…``).

## Request body

- RotateWidgetEmbedCredentialBody
  - `name` string, nullable: Label for the replacement. Defaults to the outgoing name.
  - `overlap_minutes` integer: How long the outgoing credential keeps working. 0 retires it immediately.

## Response `200`

OK

- WidgetEmbedCredentialRotation: Result of a rotation: the new credential, plus the outgoing one. `retired` reflects the outgoing credential *after* the rotation was applied — either revoked outright, or given an expiry that ends the overlap window.
  - `issued` WidgetEmbedCredentialIssued, required: The one and only response shape that carries a plaintext secret. Callers must surface `secret` to the operator immediately; it cannot be recovered afterwards because only its hash is stored.
    - `credential` WidgetEmbedCredentialRead, required
      - `id` string, required
      - `organization_id` string, required
      - `name` string, required
      - `last_four` string, required
      - `expires_at` string, date-time, nullable
      - `revoked_at` string, date-time, nullable
      - `last_used_at` string, date-time, nullable
      - `created_by_user_id` string, nullable
      - `created_at` string, date-time, required
      - `updated_at` string, date-time, nullable
      - `status` 'active' | 'expired' | 'revoked', required
    - `secret` string, required: Plaintext credential. Shown once, never retrievable again.
  - `retired` WidgetEmbedCredentialRead, required
    - `id` string, required
    - `organization_id` string, required
    - `name` string, required
    - `last_four` string, required
    - `expires_at` string, date-time, nullable
    - `revoked_at` string, date-time, nullable
    - `last_used_at` string, date-time, nullable
    - `created_by_user_id` string, nullable
    - `created_at` string, date-time, required
    - `updated_at` string, date-time, nullable
    - `status` 'active' | 'expired' | 'revoked', required

## Other responses

- `422`: Unprocessable Content

---

[API](https://skmtc.dev/nash/apis/nash-api.md) - [All operations](https://skmtc.dev/nash/apis/nash-api/llms.txt) - [OpenAPI document](https://skmtc.dev/nash/apis/nash-api/revisions/e3713837c5c9?raw)