Anmeldung und Berechtigungen

Schlüssel

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

Text

Authorization: Bearer ocost_sk_<id>_<secret>

Erstellt unter Einstellungen › API vom Inhaber oder der Buchhaltung und nur einmal angezeigt. Ocost speichert bloß einen Fingerabdruck: Einen verlorenen Schlüssel widerrufen und ersetzen Sie.
Der Anfang, ocost_sk_<id>_, ist nicht geheim. Die Einstellungen listen Schlüssel danach, mit Berechtigungen und letzter Nutzung; am Präfix ocost_sk_ erkennen Secret-Scanner ein Leck.
Ein Unternehmen je Schlüssel, und nie Personalunterlagen (Lohnabrechnungen, Gehaltslisten, Gesundheit). Eine Odoo-Firma ist ein Unternehmen mit eigenem Schlüssel.
Widerrufen gilt ab der nächsten Anfrage. Ein Schlüssel kann auch an einem Datum ablaufen.
Höchstens 10 gültige Schlüssel je Unternehmen. Zum Wechseln einen neuen erstellen, umstellen, den alten widerrufen.
Nur auf dem Server: nie in einem Browser, einer App oder einem Log.

Berechtigungen

Einstellungen › API hakt alle drei vor.

Berechtigung	Routen
`documents:write`	`POST /public/v1/files`, `DELETE /public/v1/files/{file_id}`
`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}`
`search:read`	`GET /public/v1/search`

Ablehnungen

Antwort	Wann
`401 urn:ocost:key:invalid`	Kein Schlüssel oder ein ungültiger, falscher, widerrufener, abgelaufener oder der eines gelöschten Unternehmens. Immer dieselbe Antwort.
`403 urn:ocost:key:scope`	Dem Schlüssel fehlt die Berechtigung der Route.
`429 urn:ocost:key:rate`	Zu viele Anfragen oder zu viele falsche Schlüssel von einer Adresse. Warten Sie `Retry-After` Sekunden.
`400`	Ein `Ocost-View…`-Header, den nur Ocosts Web-App schickt.

Beispiel

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());