---
title: "Roll an API key"
method: POST
path: "/organizations/current/api-keys/{id}/roll"
tags: ["Organizations"]
---

# Roll an API key

`POST /organizations/current/api-keys/{id}/roll`

## Request

- Base URL: `https://api.hookdeck.com/2025-07-01`
- URL: `https://api.hookdeck.com/2025-07-01/organizations/current/api-keys/{id}/roll`
- Auth: one of:
  - HTTP bearer
  - HTTP basic

Roll an API key: the current key expires after the rollover delay and a replacement key is returned. Organization API keys can only roll project keys whose scopes they hold on that project.

## Path parameters

- `id` string, required: API key ID

## Request body

- object
  - `delay_sec` 0 | 3600 | 86400, float, required: Seconds the current key stays valid after the roll

## Response `200`

The replacement API key

- ApiKey
  - `id` string, required: The API key ID
  - `label` string, required: The API key label
  - `key` string: The API key secret used as the bearer token
  - `team_id` string, nullable: The project the key is scoped to, or null for organization keys
  - `organization_id` string: The organization the key belongs to
  - `key_fingerprint` string, nullable: Non-secret fingerprint identifying the key
  - `scopes` string[]: Base permission scopes; ["*"] is full access
  - `grants` object: Per-subject scope overrides: keyed by project ID for organization keys, resource ID for project keys
  - `expires_at` string, nullable: When the key expires, or null while active
  - `updated_at` string: Last update timestamp
  - `created_at` string: Creation timestamp

## Other responses

- `400`: Bad Request
- `404`: Not Found

## Changes

- **2026-09-24** `9bebff6c68f9`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/hookdeck/apis/hookdeck-admin-rest-api/changes/organizations/current/api-keys/:id/roll/post.md)

---

[API](https://skmtc.dev/hookdeck/apis/hookdeck-admin-rest-api.md) - [All operations](https://skmtc.dev/hookdeck/apis/hookdeck-admin-rest-api/llms.txt) - [OpenAPI document](https://skmtc.dev/hookdeck/apis/hookdeck-admin-rest-api/revisions/b1b6f4bac5a1?raw)