Authentication

Creating and using an API key

# as an administrator (session cookie or a key with api_keys:manage)
curl -X POST "$KOMMIO_URL/account/api-keys" \
  -H "Authorization: Bearer $ADMIN_KEY" -H "Content-Type: application/json" \
  -d '{"name": "CRM sync", "permissions": ["conversations:read", "conversations:reply", "contacts:read", "contacts:write"], "expires_at": "2027-09-22T00:00:00Z"}'

# then, from the integration
curl "$KOMMIO_URL/auth/me" -H "Authorization: Bearer kmk_3f9aK2Lp8sQw1vN0zR4tY6uB2cD9eF"

const { data: key } = await api.POST("/account/api-keys", {
  body: { name: "CRM sync", permissions: ["conversations:read", "conversations:reply", "contacts:read", "contacts:write"] },
});
// key.key is the plaintext, returned once; key.prefix is what the list shows later
const sync = createKommioClient({ baseUrl: process.env.KOMMIO_URL!, apiKey: key.key! });

{ "id": 4, "name": "CRM sync", "prefix": "kmk_3f9aK2Lp", "permissions": ["conversations:read", "conversations:reply", "contacts:read", "contacts:write"], "expires_at": "2027-09-22T00:00:00Z", "created_at": "2026-09-22T09:12:00Z", "key": "kmk_3f9aK2Lp8sQw1vN0zR4tY6uB2cD9eF" }

What every credential has in common

• Send it as Authorization: Bearer <credential> (cookies for sessions).
• Missing or invalid credentials answer 401; a valid credential lacking a permission answers 403 with the permission named in detail.
• Rate limits apply per key, per workspace and per IP; see errors and limits.
• Every write is recorded in the audit trail with the credential that made it.

Two-factor and SSO for people

Password sign-in asks for a second factor when the person turned it on (/auth/mfa/*), and OpenID Connect providers that an administrator adds under Settings, Single sign-on sign people in without a password. People can list their sessions and sign them out (/auth/sessions). Details are in the security model. None of this applies to keys, apps or bots, which is why they carry narrow permissions and can be revoked in one call.