Trillet AI logo

Create API Key

Generate a new API key for authenticating requests to the Trillet API.

POSThttps://api.trillet.ai/v1/api/keys

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.

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."}.

Headers

x-workspace-idstringrequired

The workspace used for the permission check.

Request Body

metadataobject

Optional metadata to store with the key, for example {"name": "CRM integration"}.

Response Fields

keystring

The API key: 32 random letters and digits, with no prefix. Shown only in this response.

maskedboolean

false in this response (the full key is included). Listed keys are always masked.

keyPrefixstring

The first 8 characters of the key, so you can tell keys apart later.

_idstring

The key record's ID. Use it to delete the key.

userIdstring

The user the key belongs to.

typestring

user.

metadataobject

The metadata you sent ({} if none).

lastActiveAtstring

When the key was last used. null for a new key.

createdAtstring

When the key was created.

updatedAtstring

When the key record was last updated.

Errors

StatusBodyWhen
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
{
  "_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
}

Last updated on