Authentication with OAuth 2

Two ways to connect

Who connects	How	The token
Your own system or n8n	A “private app”: anyone whose role includes Integrations creates it in Integrations › For developers and copies its ID and secret.	You request it with client credentials. It lasts one hour.
Zapier, Make and other apps	They connect when you click “Allow” in meruma: the person picks the organization and accepts. You can disconnect them from meruma at any time.	Authorization code with PKCE. It lasts one hour and renews itself.

Tokens act as the person who connected the app, with only the permissions it was given. Anyone whose role includes Integrations can connect apps; webhooks are for owners and admins.

Request a token and use it

curl -u "$CLIENT_ID:$CLIENT_SECRET" \
  -d grant_type=client_credentials \
  https://api.meruma.app/oauth/token

The response carries access_token and expires_in (in seconds). Send it with every request:

curl https://api.meruma.app/v1/contacts \
  -H "Authorization: Bearer $ACCESS_TOKEN"

When it expires, request another one the same way. An expired or revoked token returns 401.

Permissions

Each app asks only for what it needs.

Permission	What it allows
contacts:read	Read contacts and their notes
contacts:write	Create, update and move contacts to the trash; add notes
cards:read	Read cards, pipelines, stages and their notes
cards:write	Create and update cards, move them between stages, tags and notes
webhooks:write	Subscribe and unsubscribe webhooks

GET /v1/me, the list of users and the list of custom fields need no permission: every integration needs them to map fields and owners.