Clés et autorisations
Chaque requête porte la clé d'API de votre entreprise dans l'en-tête Authorization :
Authorization: Bearer ocost_sk_<id>_<secret>curl -sS https://api.ocost.io/public/v1/files \
-H "Authorization: Bearer $OCOST_KEY"import requests
session = requests.Session()
session.headers["Authorization"] = f"Bearer {key}"
files = session.get("https://api.ocost.io/public/v1/files", timeout=15).json()const files = await fetch('https://api.ocost.io/public/v1/files', {
headers: { Authorization: `Bearer ${key}` },
}).then((r) => r.json());Clés
- PréfixeLes scanners de secrets le repèrent en cas de fuite.
- Id publicPas secret. Les paramètres listent les clés par lui.
- SecretMontré une fois. Gardez-le sur votre serveur.
Authorization: Bearer ocost_sk_…- Chaque requête
Ocost-Business: <id>- Une société du groupe, facultatif
Le propriétaire ou le comptable crée les clés sous Paramètres › Développeurs. 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.
Attention
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é.
Ocost-Business: 018f3c2a-7d1e-7b6a-9c40-2f5e8a1b3d77curl -sS https://api.ocost.io/public/v1/files \
-H "Authorization: Bearer $OCOST_KEY" \
-H "Ocost-Business: $COMPANY_ID"files = session.get(
"https://api.ocost.io/public/v1/files",
headers={"Ocost-Business": company_id},
timeout=15,
).json()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 explique comment une clé atteint plusieurs sociétés et où arrivent ses fichiers.
Changer de clé
- Créez une nouvelle clé avec les mêmes autorisations.
- Faites passer votre logiciel sur elle.
- 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 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. |