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

# Rotate an API key

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

## Request

- Base URL: `https://api.lilt.com`
- URL: `https://api.lilt.com/v2/api-keys/{id}/rotate`
- Auth: HTTP basic

Replace the prefix and secret of an existing API key, invalidating the previous secret and returning a new plaintext secret. The key's name and expiry are preserved.

The new secret is shown exactly once. Revoked keys cannot be rotated. The caller must own the key or hold `apiKey.write` on the current organization. The request body must be empty.

## Path parameters

- `id` string, required

## Response `200`

The rotated API key with its new plaintext secret (shown once only).

- ApiKeyWithSecret: A newly created or rotated API key, including the plaintext secret. The secret is shown exactly once and cannot be retrieved again. Note that `lastUsedAt` and `revokedAt` are not returned by the create and rotate operations.
  - `id` string, required: The unique identifier for the API key.
  - `name` string, required: A human-readable label for the key.
  - `prefix` string, required: The first 8 characters of the key's random portion — the part that follows the `lilt_` prefix. Safe to display.
  - `key` string, required: The full plaintext API key (`lilt_` followed by 40 hex characters). Shown once only.
  - `createdAt` string, date-time, required: ISO-8601 timestamp when the key was created.
  - `expiresAt` string, date-time, nullable: ISO-8601 timestamp when the key expires, or null if it does not expire.
  - `ownerEmail` string, nullable: Email address of the user who owns the key. Returned when creating a key; omitted when rotating one.
  - `ownerUserId` integer, nullable: Numeric identifier of the user who owns the key. Returned when creating a key; omitted when rotating one.

## Other responses

- `400`: The key has already been revoked and cannot be rotated, a non-empty request body was sent, or the authenticated user has no active organization.
- `401`: The request is not authenticated.
- `403`: The caller does not own the key and lacks `apiKey.write`.
- `404`: API key not found, or belongs to another organization.
- `default`: Unexpected error.

## Changes

- **2026-11-03** `99b66cc7808d`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/lilt/apis/lilt-api/changes/v2/api-keys/:id/rotate/post.md)

---

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