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

# Rotate an API key

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

## Request

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

Replaces an API key's secret and returns the new one once.

- The old secret stops working at once. The key keeps its ID, permissions, expiry and running jobs.
- You can rotate only a key whose permissions you hold.
- With deliver "dashboard", nothing changes yet: this returns a Dashboard link where the person rotates the key and sees the new secret.

## Path parameters

- `id` string, required

## Request body

- object
  - `deliver` 'dashboard': Return a Dashboard link instead of the secret, so the secret never reaches this client

## Response `200`

The key and its new one-time secret; With deliver dashboard: where to finish

- union
  - ApiKeyWithSecret
    - `id` string, required: an API key ID: key_ and 32 lowercase hex digits
    - `name` string, required
    - `permissions` string[], required
    - `integration_id` string, required: an integration ID: int_ and 32 lowercase hex digits
    - `prefix` string, required: The token's visible start, pom_ and 8 hex digits, to tell keys apart
    - `created_via` 'dashboard' | 'api' | 'mcp', required: Where the key was created
    - `created_at` string, date-time, required: An ISO 8601 timestamp in UTC
    - `expires_at` string, date-time, required: An ISO 8601 timestamp in UTC
    - `last_used_at` string, date-time, required: An ISO 8601 timestamp in UTC
    - `purpose` 'connect', nullable, required: connect for a key the Connect page made, else null
    - `secret` string, required: The key's secret, shown in this answer only. Send it as a Bearer token.
  - DashboardDelivery
    - `dashboard_url` string, required: A signed-in Dashboard page where the person finishes this and sees the secret once

## Other responses

- `400`: invalid_request
- `401`: unauthorized, reauthentication_required
- `403`: permission_not_held, forbidden
- `404`: not_found
- `413`: request_too_large
- `500`: internal_error
- `503`: temporarily_unavailable

---

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