ConnectCloud Developers

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 (without identity:admin and tenant: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.

View as Markdown