---
title: "POST /v4/workspaces/{workspaceId}/api-keys"
method: POST
path: "/v4/workspaces/{workspaceId}/api-keys"
tags: ["Workspace API Keys"]
---

# POST /v4/workspaces/{workspaceId}/api-keys

`POST /v4/workspaces/{workspaceId}/api-keys`

## Request

- Base URL: `https://api.merkl.xyz` (the document declares no server; this is the origin it was published from)
- URL: `https://api.merkl.xyz/v4/workspaces/{workspaceId}/api-keys`
- Auth: `apiKey` (a scheme the document does not define)

Create a key for the caller, or for a service account with `serviceAccountId`. Needs `api_key.create`; a service account also needs `api_key.manage` on it. The secret is returned once. A workspace holds at most 5 active keys per creator (409). Managing the credentials of a service account lets the holder act with that service account's rights.

## Path parameters

- `workspaceId` string, uuid, required

## Request body

- object
  - `description` string
  - `expiresAt` string, date-time: ISO 8601, in the future
  - `serviceAccountId` string, uuid: The service account the key belongs to. Omit it for a personal key of the caller. Managing the credentials of a service account lets the holder act with that service account's rights.

## Response `200`

Response for status 200

- object
  - `id` string, required
  - `workspaceId` string, nullable, required
  - `userId` string, nullable, required: The identity that holds the key: a person or a service account
  - `prefix` string, required
  - `description` string, nullable, required
  - `tier` number, required
  - `issuedByUserId` string, nullable, required: The person who issued the key. Absent for historical keys
  - `createdAt` string, required
  - `expiresAt` string, nullable, required
  - `revokedAt` string, nullable, required
  - `rawKey` string, nullable, required: The secret. Returned once. A repeated Idempotency-Key never returns it again

## Changes

- **2026-10-22** `b32d82e3d5c9`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/merkl/apis/merkl-api/changes/v4/workspaces/:workspaceId/api-keys/post.md)

---

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