Authentication
Every ConnectCloud API authenticates with a bearer access token:
Authorization: Bearer <accessToken>
Your integration gets that token by exchanging an API key at HR. Keys are long-lived secrets you store; access tokens are short-lived (15 minutes) and are what you send to the APIs.
Your integration HR /api/hr/v1/auth/token any ConnectCloud API
│ POST, Bearer cck_… (API key) │ │
├───────────────────────────────►│ │
│◄── accessToken (15 min) ───────┤ │
│ GET/POST …, Bearer accessToken │
├────────────────────────────────────────────────────────────────────►│
│◄────────────────────────────────────────────────────────── 200 … ───┤
│ shortly before expiry: exchange the key again (there is no refresh token)
API keys
There are two kinds of keys. Both look like cck_… and are shown exactly once when created; only
a hash is stored, so a lost key cannot be recovered, only replaced.
| Personal key | Service-account key | |
|---|---|---|
| Created in the portal at | Einstellungen › Anmeldung & Sicherheit › API-Schlüssel | Einstellungen › Benutzer & Zugriff › Service-Konten & API-Schlüssel |
| Needs the permission | tenant:token:generate |
identity:admin |
| Acts as | you (your email and employee) | the service account (sa-<id>@sa.connectcloud.invalid) |
| Permissions | a subset you choose, never more than you hold at the time of every exchange | the service account's |
| Expiry | required: default 90 days, at most 365 | optional |
| Use it for | scripts and personal automations | integrations of your company with other systems |
At most 20 active keys exist per person or service account.
Prefer service accounts for production integrations. A personal key stops working when its owner leaves, is disabled, changes their email or loses a permission.
Exchanging a key
curl -X POST 'https://api.mbcom.cloud/api/hr/v1/auth/token' \
-H "Authorization: Bearer $CONNECTCLOUD_API_KEY"
| Field | Meaning |
|---|---|
accessToken |
the bearer token for every API |
tokenType |
always Bearer |
expiresIn |
seconds until expiry (at most 900, never past the key's own expiry) |
expiresAt |
expiry as RFC 3339 timestamp |
- Cache the token and reuse it until shortly before
expiresAt. Exchanging for every request wastes your rate limit. - There is no refresh token. Exchange the key again.
- Every refusal (unknown, revoked or expired key, disabled owner) answers
401 {"code": "invalid_api_key"}; the reason is deliberately not revealed. - Revoking a key, disabling its owner or service account, or removing a permission takes effect at the next exchange, so at the latest after 15 minutes.
Reference: POST /api/hr/v1/auth/token.
OAuth clients (MCP)
MCP clients such as Claude Code, ChatGPT or Cursor do not use API keys: they connect through OAuth 2.1
(authorization code with PKCE S256, public clients without a secret). The client registers itself
(registerOAuthClient), a person approves it in the portal –
as themselves (needs tenant:token:generate) or, as an administrator (identity:admin), as a
service account – and the client exchanges the code and later its refresh token at
oauthToken.
- The access token behaves like an exchanged key token: 15 minutes,
authMethod: oauth, the person's current permissions (withoutidentity:adminandtenant:token:generate) or the service account's, one tenant. - Refresh tokens rotate on every use and expire after 30 days unused. Presenting a used refresh token or authorization code again revokes the whole connection (a retry within 5 seconds is only refused).
- People disconnect clients in the portal; disabling a person or changing their email disconnects theirs.
Permissions
What a token may do is the set of permissions it carries. Every endpoint lists the
permissions it needs in its description, for example (desk:write). A token without them gets
403 {"code": "forbidden"}.
Commonly used permissions:
| Permission | Grants |
|---|---|
desk:read |
read items in the spaces visible to the tenant |
desk:write |
create and work on items |
desk:admin |
desk configuration (workflows, types, fields, automations, …) |
desk:confidential |
see confidential items (security incidents) |
hr:read |
read employees and their working-time models |
hr:write |
create and edit employees |
hr:absence:approve |
see and decide every absence |
hr:time:manage |
everyone's time entries, timesheets, month closing, export |
hr:work:manage |
everyone's work entries (Leistungen) and days: list, approve, take back and correct them; work entry settings |
hr:work:billing |
rates, bill approved work: batches (Abrechnungen) to trade, billing overview; payment plans of desk projects |
hr:travel:approve |
see every travel expense report, approve and reject submitted ones |
hr:travel:manage |
release travel expense reports, transfer them to trade (purchasing), maintain travel rates |
hr:recruiting:read |
read every job posting and application (people named on a posting's access list see that posting with their sign-in, not with a key) |
hr:recruiting:manage |
job postings, applications of every posting, applicant mail, interviews, stages, application forms and retention |
tenant:access |
own absences, work entries (book, stopwatch, my day), time entries, timesheet, stamp clock and travel expense reports; who of the colleagues is absent (queryPresence) |
comms:read |
delivery log, received webhooks |
comms:admin |
channels, inbound webhooks, retrying deliveries |
tenant:dms:read / tenant:dms:write / tenant:dms:admin |
read, upload and manage documents |
tenant:masterdata:read / tenant:masterdata:write |
read and change addresses, contacts, articles |
tenant:crm:read / tenant:crm:write |
read and change leads, campaigns, opportunities, activities |
tenant:crm:admin |
pipeline stages, CRM settings, custom fields and retention |
tenant:search:read |
full-text search (called tenant:opensearch:read until November 2026; keys were renamed) |
tenant:trade:sales:read / tenant:trade:sales:write |
read and change sales documents: offers, order confirmations, delivery notes, invoice and credit note drafts (trade) |
tenant:trade:purchasing:read / tenant:trade:purchasing:write |
read and change purchase orders, goods receipts and supplier delivery notes; read purchase recommendations, carts and the distributor catalogue (trade) |
tenant:trade:inbound:read / tenant:trade:inbound:write / tenant:trade:inbound:approve |
read, correct and match inbound invoices / release, reject or reopen them (trade) |
tenant:trade:contract:read / tenant:trade:contract:write |
read and change customer and back-to-back contracts (trade) |
tenant:trade:sales|purchasing|inbound:* by type |
…/sales/transactions serves every document type: the permission of the document's area applies (outgoing types sales, incoming types purchasing, inbound invoices inbound) (trade) |
tenant:delivery-note:post |
confirm supplier delivery notes and post their goods receipt (trade) |
tenant:egis-cart:write / tenant:egis-order:send |
put articles into EGIS shopping carts / send purchase orders through EGIS (trade) |
tenant:stock:read / tenant:stock:write |
see stock levels, rules and movements / set minimum stock, book corrections and inventory counts (trade) |
tenant:purchase-order:send |
send purchase orders to their supplier by distributor API or mail, or record them as ordered by hand (trade) |
tenant:trade:invoice:issue |
issue draft invoices and credit notes as validated XRechnung and send them (trade) |
tenant:purchase-recommendation:write / tenant:purchase-cart:write |
dismiss, restore and recompute purchase recommendations / keep purchase carts, optimize them, create purchase orders and cancel sales orders; sending each order also needs its channel's permission, tenant:egis-order:send for EGIS, tenant:purchase-order:send for every other channel (trade) |
tenant:flows:read / tenant:flows:write / tenant:flows:admin |
see tenant flows and their runs / build, publish and start your own personal flows / tenant flows, live test runs (flows) |
tenant:flows:tasks |
the task inbox of flows – a person's approvals and forms (personal keys only, see Flows) |
tenant:settings:read / tenant:settings:write |
module settings (DMS, master data lookups, CRM, workflow) |
The full list for a module is in the Permissions table of its reference page.
Some routes never accept API keys, whatever the permissions: managing API keys, service accounts,
passkeys, personal notification settings and the AI assistant need a person signed in to the
portal and answer 403 {"code": "session_required"}. They are not part of this reference.
Tenants
A token belongs to exactly one tenant (a customer number and tenant name). Every request acts in that tenant; there is no parameter to address another one and data of other tenants is never visible. An integration that serves several tenants needs one key per tenant.
Security checklist
- Store keys in a secret manager, never in source code, logs or URLs.
- Give every integration its own service account with the smallest set of permissions.
- Set an expiry and rotate keys: create the new key, deploy it, then revoke the old one.
- Only send tokens over HTTPS to the ConnectCloud origin. Tokens are JWTs, but treat them as opaque: their claims are not part of the API contract.