--- title: API-Tokens mit Benutzerrechten anlegen und verwenden description: Lege in helloHQ API-Clients mit Sync-Token oder userbasiertem Token an und erfahre, wie die API Benutzerrechte prüft und was ein 403-Fehler bedeutet. --- [Zu Content springen](https://hellohq-helpcenter.everii.io/api-tokens-benutzerrechte#main-content) Deutsch Untermenü für Übersetzungen anzeigen Hauptnavigation öffnen Hauptnavigation schließen - Deutsch Untermenü für Übersetzungen anzeigen Wie können wir dir helfen? - Es gibt keine Vorschläge, da das Suchfeld leer ist. 1. [helloHQ Helpcenter](https://hellohq-helpcenter.everii.io/?hsLang=de) 2. [Schnittstellen, API & App](https://hellohq-helpcenter.everii.io/schnittstellen-api-app?hsLang=de) 3. [API](https://hellohq-helpcenter.everii.io/schnittstellen-api-app?hsLang=de#api) # API-Tokens mit Benutzerrechten anlegen und verwenden *Mit einem userbasierten Token darf die API nur das, was der zugeordnete User in helloHQ darf. Dieser Artikel zeigt dir, welche Token-Arten es gibt, wie du einen API-Client anlegst und was bei fehlenden Rechten passiert.* ### **Welche Token-Arten gibt es?** Jeder Token hat eine **Version**. Du siehst sie in der Spalte **„Token-Version"** der Token-Übersicht. | Token | Version | Rechteprüfung in der API | | --- | --- | --- | | Ältere Tokens | V1 | keine *(unverändert)* | | Userbasierter Token | V2 | Rechte des Users aus dem Modul-Admin | | Sync-Token | V2 | keine, voller Zugriff | - **Userbasierter Token:** Die API prüft bei jedem Aufruf die Rechte des zugeordneten Users. - **Sync-Token:** Er läuft auf den internen Admin-User. Damit kannst du alle Daten abrufen, anlegen und ändern. - **V1-Tokens:** Sie funktionieren unverändert weiter. - **Login-Tokens:** Tokens aus `POST /v2/Authenticate/Login` sind userbasiert (V2). Es gelten die Rechte des angemeldeten Users. Die Version eines bestehenden Tokens kannst du nicht ändern. Möchtest du einen V1-Token auf Rechteprüfung umstellen, lege einen neuen Token an. --- ### **Einen API-Client anlegen** Im Dialog **„API-Client anlegen"** gibt es die Checkbox **„Sync token"**. Sie ist standardmäßig **aktiviert**. - **Mit Häkchen (Sync-Token):** Die API prüft keine Berechtigungen. Im Dialog steht dazu ein Warnhinweis. - **Ohne Häkchen (userbasierter Token):** Du wählst einen User und ein Subsystem. Der Zugriff ist auf die Rechte dieses Users beschränkt. Die API prüft etwas strenger als die Oberfläche. In Einzelfällen liefert die API deshalb weniger Daten, als der User in helloHQ sieht. ### **Schritte** 1. Öffne die Verwaltung der API-Clients im Admin-Bereich \> Einstellungen \> API-Clients. 2. Wähle **„API-Client anlegen"**. 3. Entferne das Häkchen bei **„Sync token"**, wenn der Token nur die Rechte eines Users haben soll. 4. Wähle den **User** und das **Subsystem**. 5. Speichere den API-Client und kopiere den Token. 6. Prüfe in der Token-Übersicht, dass die **„Token-Version"** V2 zeigt. 7. Teste einen Aufruf mit dem Token. --- ### **Wie prüft die API die Rechte?** Jeder Endpunkt gehört zu einem oder mehreren **Modulen** aus dem Modul-Admin. - **Lesen (GET):** Der User braucht das Leserecht des Moduls. - **Schreiben (POST, PUT, PATCH, DELETE):** Der User braucht das Schreibrecht des Moduls. - **Mehrere Module:** Es reicht das Recht auf eines davon. #### **Belege** Bei Belegen entscheidet der **Belegtyp**, welches Modul gilt: - **Rechnungen:** Rechnung, Akonto-, Schluss- und Storno-Rechnung, Gutschrift, Mahnung, Zahlungserinnerung - **Eingangsrechnungen:** Eingangsrechnung - **Angebote:** Angebot, Auftragsbestätigung - **Bestellungen:** Bestellung, Preisanfrage Hat der User kein Recht für einen Belegtyp, ist ein solcher Beleg für ihn nicht vorhanden. Die API antwortet dann mit 404. Belegtypen ohne Modul-Zuordnung, zum Beispiel Lieferscheine, kannst du mit userbasierten Tokens aktuell nicht abrufen. #### **Eigene Daten** Abwesenheiten und Arbeitszeiten kannst du für die **eigenen** Einträge immer lesen, anlegen und ändern. Die Listen enthalten dann nur deine eigenen Einträge. Was passiert bei fehlenden Rechten? Fehlt ein Recht, antwortet die API mit **403 Forbidden**. Die Meldung nennt, welche Module mit welcher Rechtestufe Zugriff gewährt hätten. Außerdem steht dort die aktuelle Rechtestufe des Users. Beispiel: ``` {"message": "Access to this resource is forbidden. Needed rights: CompanyDetails (Read: 3), or AdminMasterData (Read: 5). Your current permission level is 2"} ``` So siehst du direkt, welches Recht du im Modul-Admin vergeben musst. Änderungen an Rechten gelten in der API mit einer kurzen Verzögerung: - **Rechte im Modul-Admin:** nach spätestens 60 Sekunden - **Gruppenzuordnung eines Users:** nach spätestens 30 Sekunden In der Oberfläche gelten Änderungen sofort. --- ### **Fehlermeldungen und was sie bedeuten** - **403 Forbidden:** Lies das benötigte Modul und die Rechtestufe in der Meldung. Vergib dem User das Recht im Modul-Admin und warte bis zu 60 Sekunden. - **Ein Beleg fehlt (404):** Der User hat kein Recht für den Belegtyp, oder der Belegtyp ist keinem Modul zugeordnet. Prüfe die Rechte für Rechnungen, Eingangsrechnungen, Angebote und Bestellungen. - **Ein Endpunkt liefert 403, obwohl der User alle Rechte hat:** Endpunkte, die nicht in der API-Dokumentation (Swagger) stehen, sind mit userbasierten Tokens nicht nutzbar. Verwende dafür einen Sync-Token. \[Aussage von der Fachabteilung bestätigen lassen\] Mehr zur API findest du in der Entwicklerdokumentation: [https://developer.hellohq.io/](https://developer.hellohq.io/) - [Mein helloHQ](https://hellohq-helpcenter.everii.io/mein-hellohq?hsLang=de#main-content) - [Mein helloHQ](https://hellohq-helpcenter.everii.io/mein-hellohq?hsLang=de#mein-hellohq) - [helloHQ Interface](https://hellohq-helpcenter.everii.io/mein-hellohq?hsLang=de#hellohq-interface) - [CRM](https://hellohq-helpcenter.everii.io/crm?hsLang=de#main-content) - [Unternehmen](https://hellohq-helpcenter.everii.io/crm?hsLang=de#unternehmen) - [Leads](https://hellohq-helpcenter.everii.io/crm?hsLang=de#leads) - [Datenexport](https://hellohq-helpcenter.everii.io/crm?hsLang=de#datenexport) - [Projekte](https://hellohq-helpcenter.everii.io/projekte?hsLang=de#main-content) - [Projekte](https://hellohq-helpcenter.everii.io/projekte?hsLang=de#projekte) - [Projektdetails](https://hellohq-helpcenter.everii.io/projekte?hsLang=de#projektdetails) - [Projekreporting / Projektzeiterfassung](https://hellohq-helpcenter.everii.io/projekte?hsLang=de#projekreporting-projektzeiterfassung) - [Belege](https://hellohq-helpcenter.everii.io/belege?hsLang=de#main-content) - [Allgemein](https://hellohq-helpcenter.everii.io/belege?hsLang=de#allgemein) - [Belege](https://hellohq-helpcenter.everii.io/belege?hsLang=de#belege) - [Planumsätze](https://hellohq-helpcenter.everii.io/belege?hsLang=de#planums%C3%A4tze) - [DATEV](https://hellohq-helpcenter.everii.io/belege?hsLang=de#datev) - [Sonstiges](https://hellohq-helpcenter.everii.io/belege?hsLang=de#sonstiges) - [Benutzer & Arbeitszeitverwaltung](https://hellohq-helpcenter.everii.io/benutzer-arbeitszeitverwaltung?hsLang=de#main-content) - [Benutzer](https://hellohq-helpcenter.everii.io/benutzer-arbeitszeitverwaltung?hsLang=de#benutzer) - [Benutzerverwaltung](https://hellohq-helpcenter.everii.io/benutzer-arbeitszeitverwaltung?hsLang=de#benutzerverwaltung) - [Präsenszeiterfassung](https://hellohq-helpcenter.everii.io/benutzer-arbeitszeitverwaltung?hsLang=de#pr%C3%A4senszeiterfassung) - [Controlling](https://hellohq-helpcenter.everii.io/controlling?hsLang=de#main-content) - [Controllings einrichten](https://hellohq-helpcenter.everii.io/controlling?hsLang=de#controllings-einrichten) - [Controlling Module](https://hellohq-helpcenter.everii.io/controlling?hsLang=de#controlling-module) - [Controlling Module - Alter Finanzprozess](https://hellohq-helpcenter.everii.io/controlling?hsLang=de#controlling-module-alter-finanzprozess) - [Admin](https://hellohq-helpcenter.everii.io/admin?hsLang=de#main-content) - [Rechtemanagement](https://hellohq-helpcenter.everii.io/admin?hsLang=de#rechtemanagement) - [Beleg-Standardwerte](https://hellohq-helpcenter.everii.io/admin?hsLang=de#beleg-standardwerte) - [Leistungen](https://hellohq-helpcenter.everii.io/admin?hsLang=de#leistungen) - [Belegvorlagen](https://hellohq-helpcenter.everii.io/admin?hsLang=de#belegvorlagen) - [Einstellungen](https://hellohq-helpcenter.everii.io/admin?hsLang=de#einstellungen) - [Löschverwaltung](https://hellohq-helpcenter.everii.io/admin?hsLang=de#l%C3%B6schverwaltung) - [Workflows](https://hellohq-helpcenter.everii.io/admin?hsLang=de#workflows) - [Ressourcen](https://hellohq-helpcenter.everii.io/admin?hsLang=de#ressourcen) - [Artikel](https://hellohq-helpcenter.everii.io/admin?hsLang=de#artikel) - [Standardwerte](https://hellohq-helpcenter.everii.io/admin?hsLang=de#standardwerte) - [Belegtexte (1.9)](https://hellohq-helpcenter.everii.io/admin?hsLang=de#belegtexte-1-9) - [Schnittstellen, API & App](https://hellohq-helpcenter.everii.io/schnittstellen-api-app?hsLang=de#main-content) - [Excel AddIn 2.0](https://hellohq-helpcenter.everii.io/schnittstellen-api-app?hsLang=de#excel-addin-2-0) - [Excel Auswertung per API](https://hellohq-helpcenter.everii.io/schnittstellen-api-app?hsLang=de#excel-auswertung-per-api) - [Jira](https://hellohq-helpcenter.everii.io/schnittstellen-api-app?hsLang=de#jira) - [Exchange Sync](https://hellohq-helpcenter.everii.io/schnittstellen-api-app?hsLang=de#exchange-sync) - [API](https://hellohq-helpcenter.everii.io/schnittstellen-api-app?hsLang=de#api) - [Weitere Schnittstellen](https://hellohq-helpcenter.everii.io/schnittstellen-api-app?hsLang=de#weitere-schnittstellen) - [Support](https://hellohq-helpcenter.everii.io/support?hsLang=de) - [Accountverwaltung](https://hellohq-helpcenter.everii.io/accountverwaltung?hsLang=de) - [helloHQ Updates / Releases](https://hellohq-helpcenter.everii.io/hellohq-updates-releases?hsLang=de#main-content) - [Updates 2026](https://hellohq-helpcenter.everii.io/hellohq-updates-releases?hsLang=de#updates-2026) - [Updates 2025](https://hellohq-helpcenter.everii.io/hellohq-updates-releases?hsLang=de#updates-2025) - [Updates 2024](https://hellohq-helpcenter.everii.io/hellohq-updates-releases?hsLang=de#updates-2024) - [Updates 2023](https://hellohq-helpcenter.everii.io/hellohq-updates-releases?hsLang=de#updates-2023) - [Updates 2022](https://hellohq-helpcenter.everii.io/hellohq-updates-releases?hsLang=de#updates-2022) - [Updates 2021](https://hellohq-helpcenter.everii.io/hellohq-updates-releases?hsLang=de#updates-2021) - [Updates 2020](https://hellohq-helpcenter.everii.io/hellohq-updates-releases?hsLang=de#updates-2020) [![Chill listening crop-3](https://hellohq-helpcenter.everii.io/hs-fs/hubfs/logo-icon-XL%20HC.png?width=24&height=24&name=logo-icon-XL%20HC.png "Chill listening crop-3")](https://www.hellohq.io/) helloHQ Helpcenter Copyright © 2026, everii Group GmbH