Authentifizieren Sie sich mit der Notiondesk API mithilfe der API-Schlüssel.

Jede API-Anfrage an Notiondesk wird mit einem Bearer-Token authentifiziert: einem Workspace-API-Schlüssel oder einem OAuth-Zugriffstoken für Anwendungen, die im Namen anderer Notiondesk-Kunden agieren. Dieser Artikel beschreibt, wie Sie einen Notiondesk-API-Schlüssel erstellen, seine Gültigkeitsbereiche festlegen, ihn mit Ihren Anfragen senden und ihn rotieren oder widerrufen.

Verwenden Sie einen API-Schlüssel für Automatisierungen, die Sie in Ihrem eigenen Arbeitsbereich ausführen: ein Skript, einen geplanten Job, einen CI-Schritt oder ein internes Tool. Wenn Sie eine Anwendung entwickeln, auf die sich andere Notiondesk-Kunden verbinden, verwenden Sie stattdessen OAuth .

Bevor Sie beginnen

• Ihr Arbeitsbereich ist auf einem Enterprise-Plan.

• Sie sind der Inhaber des Arbeitsbereichs oder ein Administrator.

Erstellen Sie einen Notiondesk API-Schlüssel

1. Klicken Sie in Ihrem Notiondesk-Dashboard auf Einstellungen .

2. Unter „Workspace“ öffnen Sie „Developers“ und anschließend „API-Schlüssel“ .

3. Klicken Sie auf „Schlüssel erstellen“ .

4. Geben Sie eine Bezeichnung ein, die angibt, wofür der Schlüssel bestimmt ist, zum Beispiel CI automation oder Redirect import.

5. Wählen Sie unter „Bereiche“ nur die Bereiche aus, die die Integration benötigt. Siehe „Die richtigen Bereiche auswählen“ .

6. Wählen Sie ein Ablaufdatum : 30 Tage , 90 Tage , 1 Jahr oder kein Ablaufdatum .

7. Klicken Sie auf Erstellen .

8. Klicken Sie auf „Schlüssel kopieren“ und speichern Sie den Schlüssel in Ihrem Geheimnismanager oder in Umgebungsvariablen.

9. Klicken Sie hier. Ich habe den Schlüssel gespeichert .

Der Schlüssel wird nur einmal angezeigt. Sollten Sie ihn verlieren, drehen Sie den Schlüssel, um ein neues Geheimnis zu erhalten.

Hinweis: Wenn beim Erstellen eines API-Schlüssels ein Schlosssymbol und der Tooltip „Verfügbar in Tarifen mit API-Zugriff“ angezeigt werden, ist die API in Ihrem Tarif nicht enthalten. Durch Klicken darauf öffnen Sie die Upgrade-Optionen.

Wählen Sie die richtigen Zielfernrohre

Ein Scope ist eine Berechtigung, die einem Schlüssel zugeordnet ist. Jede Notiondesk API-Route benötigt einen Scope, und ein Schlüssel kann mehrere Scopes enthalten.

Weisen Sie jeder Integration den kleinstmöglichen Satz von Gültigkeitsbereichen zu, den sie benötigt:

Wie Arbeitsbereichsrollen einen Schlüssel einschränken

Ein Schlüssel kann in Ihrem Arbeitsbereich nie mehr leisten, als die Person, die ihn erstellt hat, leisten kann.

Ändert sich die Rolle des Erstellers, ändern sich auch die Gültigkeitsbereiche des Schlüssels. Verlässt der Ersteller den Arbeitsbereich, verliert der Schlüssel seine Funktion. Informationen zur Rollenverwaltung finden Sie unter „So laden Sie ein Teammitglied ein“ .

Senden Sie den Schlüssel mit jeder Anfrage.

Senden Sie den Schlüssel im Authorization-Header mit dem Bearer-Schema:

Eine 200 OK-Nachricht mit einer Liste Ihrer Hilfezentren bestätigt die Funktionsfähigkeit des Schlüssels. Ein Schlüssel funktioniert für jedes Hilfezentrum in seinem Arbeitsbereich.

Dieselbe Anfrage in JavaScript:

Und in Python:

Bewahren Sie Ihren Notiondesk API-Schlüssel sicher auf.

curl "<https://api.notiondesk.so/sites>" \
  -H "Authorization: Bearer $NOTIONDESK_API_KEY" \
  -H "nd-version: 2026-10-16"

const response = await fetch("<https://api.notiondesk.so/sites>", {
  headers: {
    Authorization: `Bearer ${process.env.NOTIONDESK_API_KEY}`,
    "nd-version": "2026-10-16",
  },
});

const sites = await response.json();

import os
import requests

response = requests.get(
    "<https://api.notiondesk.so/sites>",
    headers={
        "Authorization": f"Bearer {os.environ['NOTIONDESK_API_KEY']}",
        "nd-version": "2026-10-16",
    },
)
sites = response.json()

• Bewahren Sie Schlüssel auf Ihrem Server auf. Speichern Sie Schlüssel niemals im Browsercode, in einer mobilen App oder in einem öffentlichen Repository.

• Speichern Sie Schlüssel in Umgebungsvariablen oder einem Geheimnismanager, nicht im Quellcode.

• Erstellen Sie für jede Integration einen eigenen Schlüssel mit eigener Bezeichnung, damit Sie einen Schlüssel widerrufen können, ohne die anderen zu beeinträchtigen.

• Wählen Sie ein Ablaufdatum für Schlüssel, die von temporären Skripten verwendet werden.

• Tauschen Sie einen Schlüssel aus, wenn jemand, der ihn kannte, Ihr Team verlässt.

• Prüfen Sie die Spalte „Zuletzt verwendet“ und widerrufen Sie Schlüssel, die niemand mehr benutzt.

Einen Schlüssel drehen oder widerrufen

Öffnen Sie Einstellungen > Entwickler > API-Schlüssel und verwenden Sie das Menü am Ende der Schlüsselzeile.

„Rotieren“ ersetzt das Geheimnis. Bestätigen Sie mit „Rotieren“ : Das aktuelle Geheimnis ist sofort ungültig und das neue wird einmalig angezeigt. Aktualisieren Sie Ihre Integration umgehend. Ein abgelaufener Schlüssel kann nicht rotiert werden; erstellen Sie stattdessen einen Ersatz.

Mit „Widerrufen“ wird der Schlüssel dauerhaft deaktiviert. Bestätigung mit „Widerrufen“ : Automatisierungen, die diesen Schlüssel verwenden, funktionieren sofort nicht mehr, und diese Änderung kann nicht rückgängig gemacht werden.

Fehlerbehebung bei der Authentifizierung

WWW-Authenticate: Bearer error="insufficient_scope", scope="sync"

Häufig gestellte Fragen

Was kommt als Nächstes?

• Legen Sie los mit der Notiondesk REST-API.

• Verbinden Sie Ihre App mit Notiondesk über OAuth

• Behandelt API-Fehler, Ratenbegrenzungen und Wiederholungsversuche der Klasse Notiondesk