---
title: "Rotate an API key"
method: POST
path: "/user-service/api-keys/{keyId}/rotate"
tags: ["ApiKeys"]
---

# Rotate an API key

`POST /user-service/api-keys/{keyId}/rotate`

Generate a new secret for an existing API key, invalidating the old secret. Optionally update alias, description, and expiration date.

## Request body

- ApiKeyRotateRequest
  - `alias` string, nullable — Human-readable alias for the API key
  - `description` string, nullable — Description of the API key's purpose
  - `expires_at` string, date-time, nullable — When the API key should expire (must be in the future, RFC3339 format)

## Response `200`

API key rotated successfully

- ApiKeyResponse
  - `id` string, uuid, required — Unique identifier for the API key
  - `key` string, required — The key identifier (defaults to id for legacy keys, can be updated to any string value)
  - `is_legacy` boolean, required — Whether this is a legacy API key
  - `account_id` string, required — Account identifier this API key belongs to
  - `type` 'TEAM' | 'USER', required — Type of API key (scope)
  - `user_id` string, uuid, nullable — User ID if this is a user-scoped API key
  - `user_name` string, nullable — Name of the user if this is a user-scoped API key
  - `team_id` string, uuid, nullable — Team ID if this is a team-scoped API key
  - `team_name` string, nullable — Name of the team if this is a team-scoped API key
  - `alias` string, nullable — Human-readable alias for the API key
  - `description` string, nullable — Description of the API key's purpose
  - `expires_at` string, date-time, nullable — When the API key expires
  - `last_used` string, date-time, nullable — When the API key was last used for authentication
  - `created_by` string, uuid, nullable — User ID of the person who created this API key
  - `created_by_name` string, nullable — Name of the user who created this API key
  - `created_at` string, date-time, required — When the API key was created
  - `updated_at` string, date-time — When the API key was last updated

## Other responses

- `401` — Unauthorized
- `403` — Forbidden
- `404` — API key not found

---

[API](https://skmtc.net/firefly/apis/firefly-user-management-service-api.md) · [All operations](https://skmtc.net/firefly/apis/firefly-user-management-service-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/firefly/firefly-user-management-service-api/revisions/3d5d69795558/schema)