API-Schlüssel und Zugriff für Schnittstellen in Odoo

Wann dieser Weg passt

Dieser Artikel beschreibt die Anmeldung einer externen Software bei der JSON-2-API von Odoo 20.0 (Pfad /json/2, seit Odoo 19.0). Welche Schnittstelle sich für welchen Zweck eignet, steht im API-Überblick. Die älteren RPC-Dienste sind laut Dokumentation abgekündigt; auch dort ersetzt der API-Schlüssel das Passwort, der Login bleibt in Gebrauch.

Schritt für Schritt: Zugriff einrichten

Schritt 1: Tarif und Voraussetzung prüfen

Laut Dokumentation zu Odoo 20.0 ist der Zugriff über die externe API nur in den Odoo-Tarifen Custom verfügbar, nicht in One App Free und Standard. Die Preisseite von Odoo S.A. beschreibt als externe API Software, die selbst Aufrufe an Odoo richtet; Aufrufe, die Odoo auslöst (zum Beispiel an einen Zahlungsanbieter), zählen nicht dazu. Die Tarifregel nennt die Dokumentation für die Odoo-Tarife (Preisseite: Enterprise); für eine selbst betriebene Community nennt sie keine. Klären Sie die Lage vor der Entwicklung für Ihren Vertrag.

Schritt 2: Eigenen technischen Benutzer anlegen

Für dauerhafte Anbindungen empfiehlt die Dokumentation eigene Bot-Benutzer. Genannte Vorteile: Sie können dem Bot nur die nötigen Rechte geben, und die Felder des Zugriffsprotokolls nennen das Bot-Konto, es wird keine Person nachgeahmt. Die Dokumentation nennt außerdem die Möglichkeit, das Passwort leer zu lassen; weil sie aber nur die Schlüsselerzeugung im eigenen Profil des Benutzers beschreibt, geht diese Anleitung von einem Bot-Konto mit gesetztem starkem Passwort aus, das nur Sie im Passwortspeicher halten. Ein persönliches Konto ist nach der Dokumentation nur zum Erkunden und für einmalige Skripte vertretbar.

Legen Sie den Benutzer unter Einstellungen ‣ Benutzer ‣ Neu an (Administratorrechte nötig). Der Benutzer muss intern sein: Im Community-Quellcode 20.0 lehnt Odoo die Schlüsselerzeugung für andere Benutzerarten ab. Ob der Bot im Vertrag als zahlender Benutzer gilt, klären Sie vorab; die Preisseite definiert als zahlend, wer Zugang zum Backend hat, um Dokumente anzulegen, anzusehen oder zu bearbeiten.

Schritt 3: Rechte nach dem Minimalprinzip setzen

Die JSON-2-API prüft jede Operation gegen Zugriffsrechte, Datensatzregeln und Feldzugriffe des Benutzers. Setzen Sie die Rechte im Reiter Zugriffsrechte des Benutzers; je Anwendung nennt die Dokumentation als häufigste Optionen leer, Benutzer: eigene Dokumente, Benutzer: alle Dokumente und Administrator (die Auswahl hängt von der App ab). Als redaktionelle Empfehlung für den Entwurf:

Anwendungsfall (erfundenes Beispiel)	Vorgehen
Ein Reportingwerkzeug liest Kundenstammdaten	Bot ohne Administratorrechte; nur die App, aus der gelesen wird, und nur so hoch, dass der Lese-Aufruf in der Testdatenbank gelingt
Ein Shop legt Aufträge an	Zugriff auf Verkauf auf der niedrigsten Stufe, mit der das Anlegen gelingt; keine Einstellungsrechte
Ein Skript für einmaliges Aufräumen	persönliches Konto in der Testdatenbank, danach Schlüssel löschen

Beginnen Sie ohne Rechte, ergänzen Sie schrittweise und prüfen Sie jeden Aufruf mit dem Bot-Schlüssel. Vergeben Sie das Recht Administration (Einstellungen oder Zugriffsrechte) nicht an den Bot: Es erlaubt, andere Benutzerrechte zu ändern. Lesen Sie vor Änderungen an Zugriffsrechten die Warnung der Dokumentation, dass Fehler dazu führen können, dass niemand mehr Rechte ändern kann.

Ein Light-Benutzer hat nach Dokumentation keinen Zugriff auf Kernanwendungen wie Verkauf, Einkauf, Projekte oder Buchhaltung und wird automatisch zum Benutzer hochgestuft, wenn er mehr Rechte erhält; er eignet sich also nur für Aufgaben im Rahmen seiner Standardrechte.

Schritt 4: API-Schlüssel erzeugen

Der Schlüssel wird im Profil des Benutzers erzeugt, dem er gehört: Präferenzen (My Preferences) ‣ Reiter für die Kontosicherheit (Account Security in der API-Dokumentation, Security in der Benutzerdokumentation) ‣ New API Key. Tragen Sie eine Beschreibung und eine Dauer ein und wählen Sie Schlüssel generieren. Die Beschreibung sollte klar sein, damit Sie später erkennen, ob der Schlüssel noch gebraucht wird (zum Beispiel Dienst und Zweck). Die Dauer bestimmt die Lebenszeit; die Dokumentation empfiehlt typisch einen Tag für interaktive Nutzung und nennt höchstens drei Monate. Der Schlüssel (160 Bit nach Dokumentation) erscheint nur einmal: kopieren Sie ihn sofort in einen Passwortspeicher oder ein Secret-Verwaltungssystem, nicht in Quellcode oder Tabellen.

Melden Sie sich dafür einmalig als Bot-Benutzer an; die Dokumentation beschreibt die Erzeugung im Profil des Schlüsselinhabers.

Schritt 5: Aufruf testen

Teil des Aufrufs (Odoo 20.0)	Inhalt
Methode und Pfad	POST /json/2//, zum Beispiel res.partner/search_read
Authorization	bearer, Leerzeichen, API-Schlüssel (Pflicht)
Content-Type	application/json, Zeichensatz empfohlen (Pflicht)
X-Odoo-Database	nur nötig, wenn ein Server mehrere Datenbanken hostet und dbfilter nicht über den Host-Header wählt
User-Agent	empfohlen: Name Ihrer Software

Antwortet Odoo mit 401 und der Meldung „Invalid apikey“, ist der Schlüssel ungültig. Jeder Aufruf läuft in einer eigenen Transaktion; fassen Sie zusammengehörige Schritte in einer Methode zusammen, statt mehrere Aufrufe zu verketten.

Schritt 6: Schlüssel erneuern

Die Dokumentation nennt diese Reihenfolge: neuen Schlüssel erzeugen, sicher ablegen, prüfen, dass alle Dienste ihn verwenden, den alten erst danach widerrufen. Ein gelöschter Schlüssel lässt sich nicht wiederherstellen. Für automatische Erneuerung gibt es die Methoden res.users.apikeys.generate und revoke über die API. Sie sind standardmäßig nur Benutzern mit dem Recht Einstellungen erlaubt; für andere setzen Sie den Systemparameter base.enable_programmatic_api_keys auf True (Einstellungen ‣ Technisch ‣ Systemparameter, Entwicklermodus nötig). Ein Benutzer kann standardmäßig bis zu 10 Schlüssel programmatisch erzeugen (base.programmatic_api_keys_limit); darüber antwortet Odoo mit HTTP 422. generate erwartet einen vorhandenen gültigen Schlüssel und ein ISO-Ablaufdatum.

So prüfen Sie das Ergebnis

• Rufen Sie mit dem Schlüssel genau die Methode auf, die die Anbindung braucht, und eine, die sie nicht brauchen darf (zum Beispiel Löschen); Letztere muss mit einem Rechtefehler scheitern.
• Prüfen Sie im Benutzerprofil, dass nur der vorgesehene Schlüssel mit der erwarteten Beschreibung existiert.

Wenn etwas nicht klappt

Symptom	Ursache nach Dokumentation oder Quellcode 20.0	Lösung
401, „Invalid apikey“	Schlüssel falsch, abgelaufen oder gelöscht	neuen Schlüssel erzeugen
Zugriffsfehler bei einer Methode	Rechte des Benutzers reichen nicht (Zugriffsrechte, Datensatzregeln, Feldzugriff)	Recht gezielt ergänzen, nicht den Benutzer zum Administrator machen
„Programmatic API keys are not enabled“	Systemparameter nicht gesetzt	Parameter prüfen oder Administrator nutzen
HTTP 422 beim Erzeugen	Grenze der programmatisch erzeugten Schlüssel erreicht	alte Schlüssel widerrufen oder Grenze anpassen
HTTP 403 beim Widerrufen	Schlüssel zum Widerrufen ungültig	richtigen Schlüssel angeben
Fehlermeldung zu Dauer oder Ablaufdatum	gewählte Dauer überschreitet das Maximum der Gruppen des Benutzers	kürzere Dauer wählen

Wann Sie Hilfe holen sollten

Ziehen Sie Ihren Odoo-Partner oder den Odoo-Support hinzu, wenn Zugriffsrechte in einer Mehrfirmen-Datenbank vergeben werden, wenn die Schnittstelle Zahlungen oder Reservierungen auslöst oder wenn der Vertrag den API-Zugriff nicht eindeutig umfasst.