Schlüssel und Berechtigungen
Jede Anfrage trägt den API-Schlüssel Ihres Unternehmens im Header 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());Schlüssel
- PräfixSecret-Scanner finden es in einem Leck.
- Öffentliche IDNicht geheim. Die Einstellungen listen Schlüssel danach.
- GeheimnisNur einmal gezeigt. Bewahren Sie es auf Ihrem Server auf.
Authorization: Bearer ocost_sk_…- Jede Anfrage
Ocost-Business: <id>- Eine Firma der Gruppe, optional
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.
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());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
- Erstellen Sie einen neuen Schlüssel mit denselben Berechtigungen.
- Stellen Sie Ihre Software auf ihn um.
- 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.
| Berechtigung | Erlaubt |
|---|---|
documents:write | POST /public/v1/files, DELETE /public/v1/files/{file_id}, PATCH /public/v1/files/{file_id}, das MCP-Werkzeug 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} und die MCP-Werkzeuge, die Datensätze lesen |
search:read | GET /public/v1/search und die Suchwerkzeuge des MCP |
figures:read | Die Zahlenwerkzeuge des MCP. Nur der Inhaber erstellt einen Schlüssel damit. |
exports:write | Die Exportwerkzeuge des MCP |
MCP-Werkzeuge listet jedes Werkzeug unter seiner Berechtigung.
Kein Schlüssel liest je Personalunterlagen wie Lohnabrechnungen, Gehaltslisten oder Gesundheitsunterlagen.
Ablehnungen
| Antwort | Wann |
|---|---|
401 urn:ocost:key:invalid | Kein 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:scope | Dem Schlüssel fehlt die Berechtigung der Route. |
403 urn:ocost:key:business | Der Schlüssel erreicht die Gesellschaft nicht, die Ocost-Business nennt. |
400 urn:ocost:key:business | Ocost-Business ist keine ID einer Gesellschaft. |
429 urn:ocost:key:rate | Zu viele Anfragen, oder zu viele falsche Schlüssel von einer Adresse. Warten Sie Retry-After Sekunden. |
400 | Die Anfrage hat einen Header Ocost-View…, den nur Ocosts Web-App schickt. |