---
title: "Rotate API key"
method: POST
path: "/v1/api-keys/{id}/rotate"
tags: ["api-keys"]
---

# Rotate API key

`POST /v1/api-keys/{id}/rotate`

## Request

- Base URL: `https://api.brixsignage.com`
- URL: `https://api.brixsignage.com/v1/api-keys/{id}/rotate`
- Auth: HTTP bearer

Replaces an API key's secret with a new one, invalidating the old secret immediately. The new secret is returned exactly once, in this response. You must hold the permission to create keys at or above the location the key is pinned to.

**Notes.**
- The key keeps its id, name, permissions, location and expiry; `lastUsedAt` is reset to null. An expired key can be rotated and stays expired.

## Path parameters

- `id` string, required

## Response `200`

Success.

- object
  - `data` object, required
    - `id` string, required
    - `name` string, required
    - `preview` string, required: The first characters of the key (`ak_us_live_Ab3x`), to recognise it. Not usable as a credential.
    - `permissions` union, required: `resource.action` permissions, or `"all"` (every permission, now and later).
      - 'all'
      - string[]
    - `nodeId` string, nullable, required: The location the key is pinned to (it can act only there and below). Null = workspace-wide.
    - `lastUsedAt` string, nullable, required: ISO-8601 timestamp (UTC).
    - `expiresAt` string, nullable, required: ISO-8601 timestamp (UTC).
    - `expired` boolean, required
    - `revokedAt` string, nullable, required: ISO-8601 timestamp (UTC).
    - `createdAt` string, required: ISO-8601 timestamp (UTC).
    - `secret` string, required: The full key. Shown ONLY in this response; store it now. Send it as `Authorization: Bearer <secret>`.

## Other responses

- `401`: Missing, expired or revoked bearer token.
- `403`: The key holds permissions you cannot grant at its location, you lack `api-key.create` there, or a Brix support session.
- `404`: No such key in this workspace.
- `409`: `revoked`: a revoked key cannot be rotated; create a new one.
- `5XX`: Server error. The body carries a `requestId` to quote to support.

---

[API](https://skmtc.dev/brixsignage/apis/brix-api.md) · [All operations](https://skmtc.dev/brixsignage/apis/brix-api/llms.txt) · [OpenAPI document](https://skmtc.dev/brixsignage/apis/brix-api/revisions/02fd3665dc7d?raw)