# Clés et autorisations
> Les clés d'API : comment une requête en porte une, leur renouvellement, leurs autorisations et les refus.

Chaque requête porte la clé d'API de votre entreprise dans l'en-tête `Authorization` :

```text
Authorization: Bearer ocost_sk_<id>_<secret>
```

```bash
curl -sS https://api.ocost.io/public/v1/files \
  -H "Authorization: Bearer $OCOST_KEY"
```

```python
import requests

session = requests.Session()
session.headers["Authorization"] = f"Bearer {key}"
files = session.get("https://api.ocost.io/public/v1/files", timeout=15).json()
```

```javascript
const files = await fetch('https://api.ocost.io/public/v1/files', {
  headers: { Authorization: `Bearer ${key}` },
}).then((r) => r.json());
```

## Clés

Le propriétaire ou le comptable crée les clés sous [Paramètres › Développeurs](https://app.ocost.io/settings/api). Ocost montre une clé une fois et n'en garde qu'une empreinte. Si vous perdez une clé, révoquez-la et créez-en une nouvelle.

Le début d'une clé, `ocost_sk_<id>_`, n'est pas secret. Les Paramètres listent les clés par ce début, avec leurs autorisations et leur dernière utilisation. Les scanners de secrets repèrent le préfixe `ocost_sk_` dans une fuite.

Une clé appartient à l’entreprise où elle a été créée. Une entreprise a au plus 10 clés actives. Une clé peut aussi expirer à une date.

> [!WARNING]
> Gardez les clés sur votre serveur. N'en mettez jamais dans un navigateur, une app mobile ou un journal.

## Les sociétés d’un groupe

Le propriétaire d’un groupe de sociétés peut donner à une clé d’autres sociétés du groupe dans Paramètres › Développeurs. La clé les atteint alors toutes, y compris celles ajoutées plus tard, ou une sélection. Le support d’Ocost peut aussi les définir. Chaque changement apparaît dans Paramètres comme une visite d’Ocost.

`GET /public/v1/businesses` liste les sociétés qu’une clé atteint, la sienne d’abord. Toute clé peut le demander.

Nommez la société d’une requête avec l’en-tête `Ocost-Business`, son identifiant. Sans lui, la requête agit dans l’entreprise de la clé.

```text
Ocost-Business: 018f3c2a-7d1e-7b6a-9c40-2f5e8a1b3d77
```

```bash
curl -sS https://api.ocost.io/public/v1/files \
  -H "Authorization: Bearer $OCOST_KEY" \
  -H "Ocost-Business: $COMPANY_ID"
```

```python
files = session.get(
    "https://api.ocost.io/public/v1/files",
    headers={"Ocost-Business": company_id},
    timeout=15,
).json()
```

```javascript
const files = await fetch('https://api.ocost.io/public/v1/files', {
  headers: { Authorization: `Bearer ${key}`, 'Ocost-Business': companyId },
}).then((r) => r.json());
```

La clé et son secret restent les mêmes quand ses sociétés changent. Une société qu’elle n’atteint plus est refusée dès la requête suivante. De même pour une société qui quitte le groupe.

[Groupes de sociétés](https://ocost.io/docs/fr/groups.md) explique comment une clé atteint plusieurs sociétés et où arrivent ses fichiers.

## Changer de clé

1. Créez une nouvelle clé avec les mêmes autorisations.
2. Faites passer votre logiciel sur elle.
3. Révoquez l'ancienne clé. Ocost la refuse dès la requête suivante.

## Autorisations

Une clé ne peut faire que ce que ses autorisations permettent. Paramètres › Développeurs coche les trois premières pour une nouvelle clé.

| Autorisation | Permet |
| --- | --- |
| `documents:write` | `POST /public/v1/files`, `DELETE /public/v1/files/{file_id}`, `PATCH /public/v1/files/{file_id}`, l'outil MCP `send_file` |
| `documents:read` | `GET /public/v1/files`, `GET /public/v1/files/{file_id}`, `GET /public/v1/files/{file_id}/content`, `GET /public/v1/files/{file_id}/document`, `GET /public/v1/documents/{document_id}`, et les outils MCP qui lisent des enregistrements |
| `search:read` | `GET /public/v1/search`, et les outils de recherche du MCP |
| `figures:read` | Les outils de chiffres du MCP. Seul le propriétaire crée une clé avec elle. |
| `exports:write` | Les outils d'export du MCP |

[Outils MCP](https://ocost.io/docs/fr/tools.md) liste chaque outil sous son autorisation.

Aucune clé ne lit jamais les papiers des personnes, comme les bulletins de paie, la paie ou les papiers de santé.

## Refus

| Réponse | Quand |
| --- | --- |
| `401 urn:ocost:key:invalid` | Aucune clé, ou une clé mal formée, fausse, révoquée ou expirée, ou celle d'une entreprise supprimée. La réponse est toujours la même. |
| `403 urn:ocost:key:scope` | Il manque à la clé l'autorisation de la route. |
| `403 urn:ocost:key:business` | La clé n’atteint pas la société que nomme `Ocost-Business`. |
| `400 urn:ocost:key:business` | `Ocost-Business` n’est pas l’identifiant d’une société. |
| `429 urn:ocost:key:rate` | Trop de requêtes, ou trop de mauvaises clés depuis une même adresse. Attendez `Retry-After` secondes. |
| `400` | La requête a un en-tête `Ocost-View…`, que seule l'app web d'Ocost envoie. |

## Voir aussi

- [Groupes de sociétés](https://ocost.io/docs/fr/groups.md): Groupes de sociétés : les sociétés qu’une clé atteint, l’en-tête Ocost-Business, l’orientation par les identifiants du document, needs_company et les fichiers du groupe.
- [Limites et erreurs](https://ocost.io/docs/fr/limits.md): Les documents par mois de la formule, les limites de débit, les tailles, les erreurs RFC 9457, les nouvelles tentatives, et où les données sont gardées.
- [Connecter un assistant](https://ocost.io/docs/fr/mcp.md): Connecter un assistant au serveur MCP (https://api.ocost.io/public/mcp, les mêmes clés) : Claude Code, Claude Desktop, Cursor, claude.ai et ChatGPT par OAuth, et tout client.
- Sur ocost.io: [API and MCP](https://ocost.io/en/product/api-and-mcp)
