---
title: "Create an API key"
method: POST
path: "/v2/api-keys"
tags: ["API Keys"]
---

# Create an API key

`POST /v2/api-keys`

## Request

- Base URL: `https://api.lilt.com`
- URL: `https://api.lilt.com/v2/api-keys`
- Auth: HTTP basic

Mint a new `lilt_*` API key under the caller's current organization. Requires the `apiKey.write` permission.

The plaintext secret is returned in the `key` field of the response and is shown exactly once — store it securely, as it cannot be retrieved again. The optional `userId` lets an admin create a key on behalf of another user who already has a grant in the current organization.

## Request body

- CreateApiKeyRequest: Request body for creating a new API key.
  - `name` string, required: A human-readable label for the key (1–255 characters).
  - `expiresAt` string, date-time: Optional ISO-8601 expiry timestamp. Must be in the future. Omit for a non-expiring key.
  - `userId` integer: Optional. When provided by an admin, mints the key on behalf of this user. The target user must already have a grant in the current organization. Defaults to the authenticated caller.

## Response `201`

The created API key, including the plaintext secret (shown once only).

- ApiKeyWithSecret: A newly created or rotated API key, including the plaintext secret. The secret is shown exactly once and cannot be retrieved again. Note that `lastUsedAt` and `revokedAt` are not returned by the create and rotate operations.
  - `id` string, required: The unique identifier for the API key.
  - `name` string, required: A human-readable label for the key.
  - `prefix` string, required: The first 8 characters of the key's random portion — the part that follows the `lilt_` prefix. Safe to display.
  - `key` string, required: The full plaintext API key (`lilt_` followed by 40 hex characters). Shown once only.
  - `createdAt` string, date-time, required: ISO-8601 timestamp when the key was created.
  - `expiresAt` string, date-time, nullable: ISO-8601 timestamp when the key expires, or null if it does not expire.
  - `ownerEmail` string, nullable: Email address of the user who owns the key. Returned when creating a key; omitted when rotating one.
  - `ownerUserId` integer, nullable: Numeric identifier of the user who owns the key. Returned when creating a key; omitted when rotating one.

## Other responses

- `400`: Invalid request. Causes include: `expiresAt` is not a future ISO-8601 timestamp; the target `userId` has no grant in the organization; `name` is missing, empty, or longer than 255 characters; an unrecognized field was sent; or the authenticated user has no active organization.
- `401`: The request is not authenticated.
- `403`: The caller does not hold `apiKey.write` on the current organization.
- `default`: Unexpected error.

## Changes

- **2026-11-03** `99b66cc7808d`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/lilt/apis/lilt-api/changes/v2/api-keys/post.md)

---

[API](https://skmtc.dev/lilt/apis/lilt-api.md) - [All operations](https://skmtc.dev/lilt/apis/lilt-api/llms.txt) - [OpenAPI document](https://skmtc.dev/lilt/apis/lilt-api/revisions/66424bd9c6de?raw)