> ## Documentation Index
> Fetch the complete documentation index at: https://developers.malibou.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> How to authenticate against the malibou public API.

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.

<Note>
  Creating and revoking API keys requires an **Admin** role on the organization.
</Note>

## Create an API key

<Steps>
  <Step title="Open the API keys page">
    In the malibou app, go to [**Profile button → My company → API keys**](https://app.malibou.com/admin/company/api-keys).
  </Step>

  <Step title="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](#scopes) for the full
    list.
  </Step>

  <Step title="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.

    <Warning>
      Treat the API key like a password. Anyone with the key can read the data
      covered by its permissions on behalf of your organization.
    </Warning>
  </Step>
</Steps>

## 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.

| Scope                       | Description                                                                                                                 |
| --------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| `org:employee:read`         | Read collaborators basic data (last name, first name, personnel number, email)                                              |
| `org:employee:details:read` | Read collaborators personal data (social security number, address, phone, bank account, etc.). Requires `org:employee:read` |
| `org:contract:details:read` | Read contract data (start date and end date). Requires `org:employee:read`                                                  |
| `org:absence:read`          | Read absence requests                                                                                                       |
| `org:absence:type:read`     | Read absence type (leave code). Requires `org:absence:read`                                                                 |
| `org:work_location:read`    | Read work location and remote work requests                                                                                 |

## Partner-only scopes

Some endpoints, grouped under **Partners only** in the [API reference](/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.

<Note>
  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.
</Note>

## 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](https://app.malibou.com/admin/company/api-keys): 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:

```bash theme={null}
curl https://app.malibou.com/api/public/v1/organizations/{organizationId}/collaborators \
  -H "Authorization: Bearer YOUR_API_KEY"
```

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](/usage/errors)).

## Manage and revoke keys

The [API keys page](https://app.malibou.com/admin/company/api-keys) 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`.