Create API Key
Generate a new API key for authenticating requests to the Trillet API.
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-idstringrequiredThe workspace used for the permission check.
Request Body
metadataobjectOptional metadata to store with the key, for example {"name": "CRM integration"}.
Response Fields
keystringThe API key: 32 random letters and digits, with no prefix. Shown only in this response.
maskedbooleanfalse in this response (the full key is included). Listed keys are always masked.
keyPrefixstringThe first 8 characters of the key, so you can tell keys apart later.
_idstringThe key record's ID. Use it to delete the key.
userIdstringThe user the key belongs to.
typestringuser.
metadataobjectThe metadata you sent ({} if none).
lastActiveAtstringWhen the key was last used. null for a new key.
createdAtstringWhen the key was created.
updatedAtstringWhen the key record was last updated.
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 |
{
"_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