Clés et autorisations

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

Text
Authorization: Bearer ocost_sk_<id>_<secret>
curl -sS https://api.ocost.io/public/v1/files \
  -H "Authorization: Bearer $OCOST_KEY"

Clés

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

Text
Ocost-Business: 018f3c2a-7d1e-7b6a-9c40-2f5e8a1b3d77
curl -sS https://api.ocost.io/public/v1/files \
  -H "Authorization: Bearer $OCOST_KEY" \
  -H "Ocost-Business: $COMPANY_ID"

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é

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

AutorisationPermet
documents:writePOST /public/v1/files, DELETE /public/v1/files/{file_id}, PATCH /public/v1/files/{file_id}, l'outil MCP send_file
documents:readGET /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:readGET /public/v1/search, et les outils de recherche du MCP
figures:readLes outils de chiffres du MCP. Seul le propriétaire crée une clé avec elle.
exports:writeLes 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éponseQuand
401 urn:ocost:key:invalidAucune 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:scopeIl manque à la clé l'autorisation de la route.
403 urn:ocost:key:businessLa clé n’atteint pas la société que nomme Ocost-Business.
400 urn:ocost:key:businessOcost-Business n’est pas l’identifiant d’une société.
429 urn:ocost:key:rateTrop de requêtes, ou trop de mauvaises clés depuis une même adresse. Attendez Retry-After secondes.
400La requête a un en-tête Ocost-View…, que seule l'app web d'Ocost envoie.

Voir aussi