---
title: "Roll (rotate) a key"
method: POST
path: "/v1/keys/{keyId}/roll"
tags: ["billing"]
---

# Roll (rotate) a key

`POST /v1/keys/{keyId}/roll`

## Request

- Base URL: `https://modelglass-api.vercel.app`
- URL: `https://modelglass-api.vercel.app/v1/keys/{keyId}/roll`
- Auth: HTTP bearer

Self-service: issues a new key and transitions the target key out of service — free plan revokes it instantly, starter/pro give it a grace period (default 24h; pro can configure up to 7 days via `gracePeriodHours`). The target key must belong to the caller's own account (a key may roll itself, or another key on the same account); otherwise 404 — this is exactly the 'I just leaked my key, roll it myself, one last time' path, and it never reveals whether a keyId belonging to a different account exists.

## Path parameters

- `keyId` string, required

## Request body

- object
  - `gracePeriodHours` number: Pro/internal only; 400 on other tiers.

## Response `201`

New key issued; the target key is rolled.

- object
  - `ok` true, required
  - `data` object, required
    - `apiKey` string
    - `keyId` string
    - `display` string
    - `tier` 'free' | 'starter' | 'pro' | 'internal' | 'app'
    - `createdAt` string, date-time
    - `rolledKeyId` string
    - `rolledKeyStatus` 'revoked' | 'grace'
  - `meta` ResponseMeta, required
    - `artifact_version` integer, required
    - `built_at` string, date-time, required
    - `count` integer: Item count when `data` is a collection.

## Other responses

- `400`: Missing keyId, target key not active, or gracePeriodHours set on a non-pro tier (BAD_REQUEST).
- `401`: Missing, unknown, or revoked API key (UNAUTHORIZED / NOT_FOUND).
- `404`: Caller's key record not found, or the target key doesn't exist / belongs to a different account (NOT_FOUND).
- `429`: Over the plan's daily rate limit (RATE_LIMITED).
- `500`: Unexpected server error (INTERNAL).

---

[API](https://skmtc.dev/modelglass/apis/modelglass-read-api.md) · [All operations](https://skmtc.dev/modelglass/apis/modelglass-read-api/llms.txt) · [OpenAPI document](https://skmtc.dev/modelglass/apis/modelglass-read-api/revisions/5948ffa60462?raw)