Schlüssel und Berechtigungen

Jede Anfrage trägt den API-Schlüssel Ihres Unternehmens im Header Authorization:

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

Schlüssel

Inhaber oder Buchhaltung erstellen Schlüssel unter Einstellungen › Entwickler. Ocost zeigt einen Schlüssel einmal und speichert nur einen Fingerabdruck. Verlieren Sie einen Schlüssel, widerrufen Sie ihn und erstellen Sie einen neuen.

Der Anfang eines Schlüssels, ocost_sk_<id>_, ist nicht geheim. Die Einstellungen listen Schlüssel danach, mit Berechtigungen und letzter Nutzung. Secret-Scanner erkennen am Präfix ocost_sk_ ein Leck.

Ein Schlüssel gehört zu dem Unternehmen, in dem er erstellt wurde. Ein Unternehmen hat höchstens 10 gültige Schlüssel. Ein Schlüssel kann auch an einem Datum ablaufen.

Achtung

Halten Sie Schlüssel auf Ihrem Server. Legen Sie nie einen in einen Browser, eine mobile App oder ein Log.

Gesellschaften einer Gruppe

Der Inhaber einer Gruppe von Gesellschaften kann einem Schlüssel unter Einstellungen › Entwickler weitere davon geben. Ein Schlüssel erreicht dann alle, auch später hinzugekommene, oder eine Auswahl. Auch der Ocost-Support kann sie festlegen. Jede Änderung steht unter Einstellungen als Besuch von Ocost.

GET /public/v1/businesses listet die Gesellschaften, die ein Schlüssel erreicht, seine eigene zuerst. Jeder Schlüssel darf das fragen.

Nennen Sie die Gesellschaft einer Anfrage mit dem Header Ocost-Business, ihrer ID. Ohne ihn handelt die Anfrage im eigenen Unternehmen des Schlüssels.

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"

Schlüssel und Geheimnis bleiben gleich, wenn sich seine Gesellschaften ändern. Eine Gesellschaft, die er nicht mehr erreicht, lehnt Ocost ab der nächsten Anfrage ab. Ebenso eine, die die Gruppe verlässt.

Unternehmensgruppen erklärt, wie ein Schlüssel mehrere Gesellschaften erreicht und wo seine Dateien landen.

Einen Schlüssel wechseln

  1. Erstellen Sie einen neuen Schlüssel mit denselben Berechtigungen.
  2. Stellen Sie Ihre Software auf ihn um.
  3. Widerrufen Sie den alten Schlüssel. Ocost lehnt ihn ab der nächsten Anfrage ab.

Berechtigungen

Ein Schlüssel darf nur, was seine Berechtigungen erlauben. Einstellungen › Entwickler hakt für einen neuen Schlüssel die ersten drei vor.

BerechtigungErlaubt
documents:writePOST /public/v1/files, DELETE /public/v1/files/{file_id}, PATCH /public/v1/files/{file_id}, das MCP-Werkzeug 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} und die MCP-Werkzeuge, die Datensätze lesen
search:readGET /public/v1/search und die Suchwerkzeuge des MCP
figures:readDie Zahlenwerkzeuge des MCP. Nur der Inhaber erstellt einen Schlüssel damit.
exports:writeDie Exportwerkzeuge des MCP

MCP-Werkzeuge listet jedes Werkzeug unter seiner Berechtigung.

Kein Schlüssel liest je Personalunterlagen wie Lohnabrechnungen, Gehaltslisten oder Gesundheitsunterlagen.

Ablehnungen

AntwortWann
401 urn:ocost:key:invalidKein Schlüssel, oder ein ungültiger, falscher, widerrufener oder abgelaufener, oder der eines gelöschten Unternehmens. Die Antwort ist immer dieselbe.
403 urn:ocost:key:scopeDem Schlüssel fehlt die Berechtigung der Route.
403 urn:ocost:key:businessDer Schlüssel erreicht die Gesellschaft nicht, die Ocost-Business nennt.
400 urn:ocost:key:businessOcost-Business ist keine ID einer Gesellschaft.
429 urn:ocost:key:rateZu viele Anfragen, oder zu viele falsche Schlüssel von einer Adresse. Warten Sie Retry-After Sekunden.
400Die Anfrage hat einen Header Ocost-View…, den nur Ocosts Web-App schickt.

Siehe auch