Authentication

Every Cowdi API request is authenticated with a bearer token:

Authorization: Bearer <token>

Server-to-server integrations

Create a client in Cowdi Connect, choose the Client credentials grant, and assign the smallest set of API scopes it needs. Your service exchanges the one-time client secret for a short-lived access token, then sends that token to the Cowdi API.

Tokens come from a different host than the API, and both are per-environment — a sandbox client cannot call production.

Tokens are valid for expires_in seconds. Request one, hold it in memory, and refresh it shortly before it expires — do not fetch a new token per API call.

A client can only be granted scopes the person creating it already holds, and the token carries them in its scope claim. Calling an endpoint whose scope the client lacks returns 403. Grant the narrowest set that covers the integration; widening it later does not re-issue the credentials.

Everything Connect does is also on the API, if you would rather manage clients programmatically: POST /v1/oauth/clients creates one, and GET /v1/oauth/clients/scopes lists the scopes you can grant it.

The Quickstart walks through the complete setup and first request.

Acting on behalf of a user

Choose the Authorization code grant instead when your integration acts as the person using it rather than as itself. These clients always use PKCE — it is not optional — and they must declare their redirect_uris up front.

Send the user to /oauth2/authorize on the same host as the token endpoint above, with response_type=code, your client_id, a registered redirect_uri, a state, a nonce, and an S256 code_challenge. Exchange the returned code at the token endpoint along with the matching code_verifier. The resulting token carries the user's own permissions, so it can reach only what they can.

Testing from these docs

Every endpoint page has a Test it panel. Sign in there and the docs server attaches your access token to the request on your behalf; the token is held in an httpOnly cookie and never reaches the browser.

The request goes to the live API as you, in the organization your Cowdi session is signed in to — the panel names that organization, because there is no test mode to fall back on.

Optional sign-in for org‑specific docs

Signing in is optional. When you do:

• The reference also shows any endpoints specific to your organization.
• The API reference filters to your organization's pinned API version; operations and fields not yet available on that version are hidden. You can still try a newer version per request with the Cowdi-Version header.
• A banner links to Connect to view or change your API version.

Signed out, you see the public surface and the latest version.

Errors

The API returns standard JSON error bodies with a machine-readable code and a human-readable description. Handle 401 by obtaining or refreshing the token, 403 by checking the token's scopes and that it was issued for the target organization, and 429 by backing off and retrying.