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

# Rotate API key

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

## Request

- Base URL: `https://admin-api.exa.ai/team-management`
- URL: `https://admin-api.exa.ai/team-management/api-keys/{id}/rotate`
- Auth: API key in header `x-api-key`

Replaces an API key's secret and returns the new one. The key keeps its `publicId`, name, rate limit, budget, and usage history. The old secret keeps working for `gracePeriodSeconds` (0 revokes it immediately), so the new secret can be rolled out before the old one stops working. A key has at most one previous secret: while it is still in its grace period, rotation returns 409 unless `force` is true.

## Path parameters

- `id` string, required

## Request body

- object
  - `gracePeriodSeconds` integer, required: How long the old secret keeps working, in seconds (at most 90 days). 0 revokes it immediately.
  - `force` boolean: Rotate even if the secret replaced by an earlier rotation is still in its grace period. That secret stops working immediately.

## Response `200`

API key rotated successfully

- object
  - `apiKey` object
    - `id` string, uuid: Same value as `secret`, kept for backward compatibility. Use `publicId` to identify the key.
    - `publicId` string: Stable identifier of the API key, unchanged by rotation.
    - `secret` string: The new API key. Send it in the `x-api-key` header of Exa API requests and keep it in your secrets manager.
    - `name` string
    - `rateLimit` integer, nullable: Rate limit in requests per second
    - `budgetCents` integer, nullable: Spending budget for the API key, in cents
    - `isOverBudget` boolean: Whether the API key is currently over its budget
    - `teamId` string
    - `createdAt` string, date-time
    - `previousSecretExpiresAt` string, date-time, nullable: When the old secret stops working, or null if it was revoked immediately.

## Other responses

- `400`: Bad Request - Invalid parameters
- `401`: Unauthorized - Invalid or missing service key
- `403`: Forbidden - the key is managed by an integration
- `404`: Not Found - API key does not exist
- `409`: Conflict - the secret replaced by an earlier rotation is still in its grace period (`previous_secret_active`), or another rotation of the same key finished first (`rotation_conflict`). Nothing was changed.

## Changes

- **2026-11-03** `271bf8d70dff`: 1 info
  - endpoint added

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

---

[API](https://skmtc.dev/exa/apis/team-management-api.md) - [All operations](https://skmtc.dev/exa/apis/team-management-api/llms.txt) - [OpenAPI document](https://skmtc.dev/exa/apis/team-management-api/revisions/271bf8d70dff?raw)