---
title: "Create a new hash-based API key"
method: POST
path: "/api/v1/api-keys"
tags: ["api-keys"]
---

# Create a new hash-based API key

`POST /api/v1/api-keys`

Creates a new OpenAI-compatible API key (sk-oai-* format). Supports both permanent keys (no expiration) and expiring keys (with expiresIn parameter). The plaintext key is shown ONLY ONCE at creation time and cannot be retrieved again.

## Request body

- object
  - `data` object, required
    - `name` string, required — Human-readable name for the API key
    - `description` string — Optional description
    - `expiresIn` string — Optional expiration duration (e.g., "30d", "90d", "1h"). Omit for permanent key.
    - `subscription` string, required — Subscription ID header to scope this API key to a specific subscription.
    - `ephemeral` boolean — When true, requests an ephemeral key (short-lived); forwarded to maas-api.

## Response `201`

Created response.

- object
  - `data` object, required
    - `key` string — Plaintext API key (SHOWN ONCE, NEVER AGAIN)
    - `keyPrefix` string — Display prefix for UI (e.g., sk-oai-abc)
    - `id` string — Unique identifier for the key
    - `name` string — Name of the key
    - `createdAt` string, date-time — Creation timestamp (RFC3339)
    - `expiresAt` string, date-time — Expiration timestamp (RFC3339), omitted for permanent keys

## Other responses

- `400` — Bad Request response.
- `401` — Unauthorized response.
- `500` — Internal Server Error

## Changes

- **2026-06-23** `b980153caff7` — 1 breaking, 11 warning, 1 info
  - added the new required request property `data`
  - removed the request property `description`
  - removed the request property `ephemeral`
  - removed the request property `expiresIn`
  - …9 more
- **2026-05-07** `1c92de0246f4` — 1 info
  - added the new optional request property `ephemeral`
- **2026-04-01** `3c74049a881f` — 1 breaking
  - added the new required request property `subscription`
- **2026-03-16** `9380b41a2304` — 1 info
  - endpoint added
- **2026-02-02** `232174554498` — 1 breaking
  - api removed without deprecation

[Change history](https://skmtc.dev/opendatahub-io/apis/maas-bff-api/changes/api/v1/api-keys/post.md)

---

[API](https://skmtc.dev/opendatahub-io/apis/maas-bff-api.md) · [All operations](https://skmtc.dev/opendatahub-io/apis/maas-bff-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/opendatahub-io/maas-bff-api/revisions/f8bfb089642f/schema)