# Authentication

Every ConnectCloud API authenticates with a **bearer access token**:

```http
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.

```text
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

```bash
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](/guides/rate-limits).
- **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`](/reference/hr/exchangeApiKey).

## 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`](/reference/hr/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`](/reference/hr/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](/guides/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.
