Skip to main content
The malibou public API authenticates requests with an API key. You create a key from the malibou app, then send it as a Bearer token on every request.
Creating and revoking API keys requires an Admin role on the organization.

​
Create an API key

1

Open the API keys page

In the malibou app, go to Profile button → My company → API keys.
2

Create a key and choose permissions

Click Create an API key, give it a descriptive name (for example “Planning integration”), and tick the permissions the key should grant. Each permission limits the key to a specific kind of data. See Scopes for the full list.
3

Copy your secret

The secret is shown only once. Copy it and store it somewhere safe (a secret manager, not source control). You will not be able to view it again after closing the window.
Treat the API key like a password. Anyone with the key can read the data covered by its permissions on behalf of your organization.

​
Scopes

Each API key is granted one or more scopes that restrict what data it can access. Select only the scopes your integration actually needs.

​
Partner-only scopes

Some endpoints, grouped under Partners only in the API reference, require scopes that are not listed above (org:company:read, org:employee:health_insurance:manage). These scopes are not selectable when creating an API key from the app: they are only granted to integration partners with an approved partnership agreement with malibou. If you are interested in using these endpoints, please contact us.
If you are building a self-serve integration, you can safely ignore the Partners only section of the API reference: your API key will always return 403 on those endpoints, regardless of the permissions you select.

​
Retrieve your organization id

Every endpoint is scoped to an organization, whose id is part of the request path (/api/public/v1/organizations/{organizationId}/...). You need it before calling any endpoint. Retrieve it from the API keys page: open the actions menu (next to Create an API key) and choose Copy organization ID.

​
Authenticate your requests

Send the key in the Authorization header as a Bearer token:
Every endpoint under /api/public/v1 requires this header. A request with a missing or invalid key returns 401, and a key that lacks the permission an endpoint requires returns 403 (see Errors).

​
Manage and revoke keys

The API keys page lists every key for your organization with its name, permissions, status and creation date. API keys do not expire by default. If a key is compromised or no longer needed, revoke it from this page. Revocation is immediate and irreversible. Any request made with a revoked key returns 401.