---
title: "Create Api Key"
method: POST
path: "/v1/api-keys/"
tags: ["api-keys"]
---

# Create Api Key

`POST /v1/api-keys/`

## Request

- Base URL: `https://api.mentium.io` (the document declares no server; this is the origin it was published from)
- URL: `https://api.mentium.io/v1/api-keys/`
- Auth: HTTP bearer

Create a new API key.

A key that reads/writes TMS data operates on a connection (data box). The
caller must name the TMS connection the key binds to — any TMS connection the
workspace can see is eligible (a real external TMS like TAI/Sunnybrook, a
client push connection, or Sandbox). The server does not pick one for you:
binding is the most consequential property of a key, so it is always explicit.
A key that touches no TMS data (e.g. a webhook-trigger key) carries no
connection.

**Important**: The API key value is only returned once. Store it securely.

## Headers

- `mentium-workspace-id` string, nullable

## Request body

- ApiKeyCreateRequest: Request schema for creating an API key.
  - `name` string, required: Human-readable name for the API key
  - `integration_connection_id` string, uuid, nullable: TMS data box the key reads/writes. Required for keys with TMS-data scopes; any TMS connection in the workspace (or org-level) is eligible — TAI, Sunnybrook, Sandbox, etc. Omit for keys that touch no TMS data (e.g. webhook keys).
  - `scopes` string[], nullable: Permission scopes (defaults to all TMS API scopes if not specified)
  - `description` string, nullable: Optional description
  - `expires_at` string, date-time, nullable: Optional expiration datetime
  - `rate_limit_per_minute` integer: Rate limit per minute
  - `rate_limit_per_day` integer: Rate limit per day

## Response `201`

Successful Response

- ApiKeyCreateResponse: Response schema for a newly created API key (includes the actual key value).
  - `id` string, uuid, required
  - `name` string, required
  - `key_prefix` string, required
  - `status` 'ACTIVE' | 'REVOKED' | 'EXPIRED', required
  - `scopes` string[], required
  - `description` string, nullable, required
  - `rate_limit_per_minute` integer, required
  - `rate_limit_per_day` integer, required
  - `last_used_at` string, date-time, nullable, required
  - `usage_count` integer, required
  - `expires_at` string, date-time, nullable, required
  - `revoked_at` string, date-time, nullable, required
  - `created_at` string, date-time, required
  - `updated_at` string, date-time, required
  - `integration_connection_id` string, uuid, nullable, required
  - `created_by_user_id` string, uuid, required
  - `created_by_name` string, nullable
  - `integration_connection_name` string, nullable
  - `key` string, required: The full API key (only shown once)

## Other responses

- `404`: Not found
- `422`: Validation Error

---

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