Skip to main content
A native app signs people in through the browser, receives a token for the API and acts as that person. This page shows the flow and the endpoints an app needs for its own roles.

​
Before you start

An administrator has to allow applications to register themselves, or has to register your app. Each person decides on a consent page what the app may do for them.
An app never gets more than the person may do. A guest cannot connect an app at all, and scopes that answer about everyone on the instance go to system administrators only.

​
Sign in

1

Discover the server

Read /.well-known/oauth-authorization-server for the endpoints. Read /.well-known/oauth-protected-resource/api/v1 to learn that this server issues tokens for the data API.
2

Register the app

Register a public client with a loopback redirect address such as http://127.0.0.1:8765/callback and PKCE.
3

Open the browser

Send the person to the authorization endpoint with response_type=code, your client_id, a PKCE code_challenge (S256), the scope you need and the parameter resource=https://your-collabase.ch/api/v1. Send exactly one resource.
4

Exchange the code

Receive the code on your loopback address and exchange it at the token endpoint. Send the same resource again. Ask for offline_access to receive a refresh token.
5

Call the API

Send the access token as Authorization: Bearer. It is short lived; refresh it with the refresh token.
A token is valid for one resource only. A token issued for the MCP endpoint does not work on /api/v1, and a request for both resources at once is refused. An app that already connected for the MCP endpoint is asked to agree again for /api/v1.

​
Scopes

Scopes are an area and a level, such as tests:read. Two areas exist for apps: Ask for the area scopes of the data your app uses, for example tests:read and tests:write.

​
When access ends

The person can withdraw the consent in their profile, an administrator can switch the app off, and a locked account stops working. The next call is answered with 401. Withdrawing the consent also removes the person from the groups of your app.

​
Read the signed-in person

​
Groups for your app’s roles

Your app can keep its own groups, for example one per role, and read each person’s membership from /api/v1/me. Rules:
  • All four need the appgroups:write scope and a token issued to an app. A personal API key is refused with 403.
  • Your app changes only the groups it created. Other groups answer 403.
  • A person can be a member only after they connected your app. One person who did not connect refuses the whole call with 422 and changes nothing.
  • An administrator can rename, fill and delete app groups in Admin → Groups, where they show an App label. They cannot be given access to a space, a module or a permission: a group that an app fills never grants rights in Collabase.
Last modified on October 26, 2026