> For the complete documentation index, see [llms.txt](https://docs.oomus.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.oomus.org/api-reference/authentication.md).

# Authentication

Oomus CampaignID uses authentication **JWT (JSON Web Token)**. All API requests (except the documented public endpoints) require a valid access token in the header `Authorization`.

**Base URL:** `https://api.oomus.health`

***

## Access tokens

The access token must be included in every API request. When it expires, use the refresh token to obtain a new access token without re-entering your credentials.

***

## Endpoints

### POST /auth/register

Creates a new program account.

**Request body:**

```json
{
  "email": "contact@programme.sn",
  "password": "VotreMotDePasse!Secure",
  "name": "National Vaccination Program",
  "country": "Senegal"
}
```

**201 Created response:**

```json
{
  "id": "usr_01HXYZ123ABC",
  "email": "contact@programme.sn",
  "name": "National Vaccination Program",
  "role": "programme_admin",
  "plan": "starter",
  "status": "active",
  "created_at": "2026-05-15T09:00:00Z"
}
```

**Possible errors:**

| Code  | Description                                          |
| ----- | ---------------------------------------------------- |
| `400` | Email already in use                                 |
| `422` | Validation failed (password too weak, invalid email) |

***

### POST /auth/login

Authenticates a user and returns JWT tokens.

**Request body:**

```json
{
  "email": "contact@programme.sn",
  "password": "VotreMotDePasse!Secure"
}
```

**200 OK response (without 2FA):**

```json
{
  "access_token": "<access_token>",
  "refresh_token": "<refresh_token>",
  "token_type": "bearer",
  "requires_2fa": false,
  "programme": { "...": "..." }
}
```

**200 OK response (with 2FA enabled):**

```json
{
  "access_token": "",
  "refresh_token": "",
  "token_type": "bearer",
  "requires_2fa": true,
  "totp_token": "<totp_pending_token>"
}
```

> If `requires_2fa: true`, call `POST /auth/2fa/login` with the `totp_token` received and the TOTP code.

**Possible errors:**

| Code  | Description                         |
| ----- | ----------------------------------- |
| `401` | Incorrect credentials               |
| `403` | Account suspended                   |
| `429` | Too many attempts — try again later |

***

### POST /auth/refresh

Obtains a new access token from a valid refresh token.

**Request body:**

```json
{
  "refresh_token": "<refresh_token>"
}
```

**200 OK response:**

```json
{
  "access_token": "<nouvel_access_token>",
  "refresh_token": "<nouveau_refresh_token>",
  "token_type": "bearer"
}
```

**Possible errors:**

| Code  | Description                                |
| ----- | ------------------------------------------ |
| `401` | Invalid, expired, or revoked refresh token |

***

### POST /auth/logout

Revokes the current access token (logs out the active session).

**204 No Content response**

***

### POST /auth/logout-all

Revokes all active sessions for the account (all devices).

**204 No Content response**

***

### GET /auth/me

Returns the authenticated user's profile.

**200 OK response:**

```json
{
  "id": "usr_01HXYZ123ABC",
  "email": "contact@programme.sn",
  "name": "National Vaccination Program",
  "country": "Senegal",
  "role": "programme_admin",
  "plan": "starter",
  "status": "active",
  "balance_fcfa": 125000,
  "cards_generated": 4800,
  "is_admin": false,
  "permissions": [],
  "two_factor_enabled": false,
  "logo_url": null,
  "created_at": "2026-05-15T09:00:00Z"
}
```

***

### PATCH /auth/me

Updates the authenticated user's profile (name, country, phone).

***

### POST /auth/change-password

Changes the password. Invalidates all active sessions.

**Request body:**

```json
{
  "current_password": "AncienMotDePasse!",
  "new_password": "NouveauMotDePasse!Secure"
}
```

**204 No Content response**

***

### POST /auth/logo

Uploads the program logo (PNG / JPEG / WEBP, max 512 KB).

**Content-Type:** `multipart/form-data`

| Field  | Type   | Description                         |
| ------ | ------ | ----------------------------------- |
| `file` | `File` | PNG, JPEG, or WEBP image (≤ 512 KB) |

***

## Two-factor authentication (2FA TOTP)

2FA is based on the TOTP standard (RFC 6238), compatible with Google Authenticator, Authy, and any standard TOTP client.

### Full flow

```
1. POST /auth/login      → { requires_2fa: true, totp_token: "..." }
2. POST /auth/2fa/login  → { access_token, refresh_token } (final tokens)
```

### POST /auth/2fa/setup

Generates a TOTP secret and returns the provisioning URI.

**200 OK response:**

```json
{
  "secret": "BASE32SECRETHERE",
  "provisioning_uri": "otpauth://totp/OOMUS%20DPI:contact%40programme.sn?secret=BASE32SECRETHERE&issuer=OOMUS%20DPI"
}
```

### POST /auth/2fa/verify-setup

Enables 2FA after the code is confirmed.

```json
{ "secret": "BASE32SECRETHERE", "code": "123456" }
```

### DELETE /auth/2fa/disable

Disables 2FA. Requires confirmation of the current password.

```json
{ "current_password": "VotreMotDePasse!" }
```

### POST /auth/2fa/login

Completes 2FA authentication with the intermediate token and the TOTP code.

```json
{
  "totp_token": "<totp_pending_token>",
  "code": "123456"
}
```

**200 OK response:** final JWT tokens (same schema as `POST /auth/login`)

***

## Using the token in requests

```bash
curl -X GET https://api.oomus.health/campaigns \
  -H "Authorization: Bearer <access_token>"
```

***

## Expiration handling

### Recommended flow

```
1. Login  → store access_token + refresh_token (on the client side)
2. Use access_token for requests
3. If 401 response:
   → POST /auth/refresh with the refresh_token
   → Store the new access_token
   → Retry the request
4. If refresh_token is invalid:
   → Redirect to the login page
```

***

## Next steps

* [Campaigns & Jobs](/api-reference/campaigns-and-jobs.md)
* [Billing](/api-reference/billing.md)
* [MPI](/api-reference/mpi.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.oomus.org/api-reference/authentication.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.