---
title: "Create API Key"
api: "POST /v1/api/keys"
description: "Generate a new API key for authenticating requests to the Trillet API."
lastUpdated: "2026-11-04"
---

> **For AI agents:** the complete documentation index is at [llms.txt](https://trillet-ai.jamdesk.app/llms.txt). Append `.md` to any page URL for its markdown version.

The key belongs to **you** (the calling user), not to the workspace. It has no permissions or limits of its own: a request made with it acts as you, with your role, in whichever workspace its `x-workspace-id` header names (any workspace you're a member of).

Only a hash of the key is stored. The full key is returned **once**, in this response. Copy it now: it can't be retrieved again.

<Note>
Your role needs the `api_keys:create` permission. Otherwise the request fails with `403 {"error": "Insufficient permissions", ...}`. Connected apps (OAuth tokens, such as an MCP connector) can't create keys and get `403 {"error": "API keys cannot be managed by connected apps."}`.
</Note>

## Headers
<ParamField header="x-workspace-id" type="string" required>
The workspace used for the permission check.
</ParamField>

## Request Body

<ParamField body="metadata" type="object">
Optional metadata to store with the key, for example `{"name": "CRM integration"}`.
</ParamField>

## Response Fields

<ResponseField name="key" type="string">
The API key: 32 random letters and digits, with no prefix. Shown only in this response.
</ResponseField>

<ResponseField name="masked" type="boolean">
`false` in this response (the full key is included). Listed keys are always masked.
</ResponseField>

<ResponseField name="keyPrefix" type="string">
The first 8 characters of the key, so you can tell keys apart later.
</ResponseField>

<ResponseField name="_id" type="string">
The key record's ID. Use it to [delete the key](https://trillet-ai.jamdesk.app/v1/api-reference/endpoints/api-keys/delete).
</ResponseField>

<ResponseField name="userId" type="string">
The user the key belongs to.
</ResponseField>

<ResponseField name="type" type="string">
`user`.
</ResponseField>

<ResponseField name="metadata" type="object">
The metadata you sent (`{}` if none).
</ResponseField>

<ResponseField name="lastActiveAt" type="string">
When the key was last used. `null` for a new key.
</ResponseField>

<ResponseField name="createdAt" type="string">
When the key was created.
</ResponseField>

<ResponseField name="updatedAt" type="string">
When the key record was last updated.
</ResponseField>

## Errors

| Status | Body | When |
| --- | --- | --- |
| `403` | `{"error": "Insufficient permissions", ...}` | Your role lacks `api_keys:create` |
| `403` | `{"error": "API keys cannot be managed by connected apps."}` | The request used an OAuth (connected app) token |
| `500` | `{"error": "Internal server error"}` | Unexpected server error |

<ResponseExample>
```json
{
  "_id": "a4a4a4a4a4a4a4a4a4a4a4a4",
  "userId": "a1a1a1a1a1a1a1a1a1a1a1a1",
  "type": "user",
  "metadata": {},
  "lastActiveAt": null,
  "minutesActive": 0,
  "keyPrefix": "aB3dE5fG",
  "key": "aB3dE5fG7hJ9kL1mN3pQ5rS7tU9vW1xY",
  "masked": false,
  "createdAt": "2026-10-01T09:00:00.000Z",
  "updatedAt": "2026-10-01T09:00:00.000Z",
  "__v": 0
}
```
</ResponseExample>


---

📦 **OpenAPI specs:** Every OpenAPI specification referenced by this documentation is available as a single download — https://trillet-ai.jamdesk.app/api-specs.zip
