Authentifizierung – Dokumentation

API-Schlüssel

Jede Anfrage weist sich mit deinem API-Schlüssel aus. Schick ihn im Header x-api-key mit, dann gilt die Anfrage für dein Konto und wird mit deinem Guthaben abgerechnet.

Beim Anlegen deines Kontos erstellen wir den ersten Schlüssel automatisch. Du findest ihn unter Konto › API-Schlüssel. Dort legst du weitere Schlüssel an und löschst sie wieder.

Nimm am besten einen eigenen Schlüssel pro Anwendung oder Integration. Dann kannst du einen davon löschen, ohne die anderen anzufassen. Anfragen mit einem gelöschten Schlüssel lehnt die API sofort ab.

curl -G "https://handelsregister.ai/api/v1/fetch-organization" \
  -H "x-api-key: DEIN_API_SCHLUESSEL" \
  --data-urlencode 'q=Hetzner Online GmbH'

import requests

response = requests.get(
    "https://handelsregister.ai/api/v1/fetch-organization",
    headers={"x-api-key": "DEIN_API_SCHLUESSEL"},
    params={
        "q": "Hetzner Online GmbH",
    },
)
data = response.json()

const url = new URL("https://handelsregister.ai/api/v1/fetch-organization");
url.searchParams.append("q", "Hetzner Online GmbH");

const response = await fetch(url, {
  headers: { "x-api-key": "DEIN_API_SCHLUESSEL" },
});
const data = await response.json();

Die API steht bereit, sobald du deine E-Mail-Adresse bestätigt hast. Bis dahin antwortet sie mit 403.

Drei Wege zur Anmeldung

Die API kennt drei Wege, einen Zugang mitzuschicken. Für deinen eigenen Code ist der Header x-api-key der einfachste und sicherste.

Weg
Weg	So sieht es aus	Gilt für
API-Schlüssel im Header (empfohlen)	`x-api-key: DEIN_API_SCHLUESSEL`	Alle Endpunkte
Bearer-Token: ein Token aus `/v1/auth/tokens` oder ein OAuth-Token eines KI-Agenten	`Authorization: Bearer DEIN_TOKEN`	Alle Endpunkte außer `/v1/auth/tokens`
API-Schlüssel als Parameter in der URL	`?api_key=DEIN_API_SCHLUESSEL`	Daten-Endpunkte und `/v1/auth/tokens`; `/v1/account/*` lehnt ihn mit `400` ab

Der Parameter api_key funktioniert auf den Daten-Endpunkten weiter. URLs landen aber leicht in Logs, Verläufen und Proxys. Schick den Schlüssel deshalb im Header.

Dieselbe Anfrage mit einem Bearer-Token

curl -G "https://handelsregister.ai/api/v1/fetch-organization" \
  -H "Authorization: Bearer DEIN_TOKEN" \
  --data-urlencode "q=Hetzner Online GmbH"

Bearer-Token erstellen

Ein Bearer-Token ist ein zusätzlicher Zugang, den du selbst mit Namen, Berechtigungen und Ablaufdatum versiehst. Du erstellst es mit deinem API-Schlüssel über POST /v1/auth/tokens/create. Die Endpunkte unter /v1/auth/tokens nehmen nur den API-Schlüssel an, kein Bearer-Token.

curl -X POST "https://handelsregister.ai/api/v1/auth/tokens/create" \
  -H "x-api-key: DEIN_API_SCHLUESSEL" \
  -H "Content-Type: application/json" \
  -d '{
    "token_name": "CRM-Abgleich",
    "abilities": [
        "api:data",
        "account:read"
    ],
    "expires_at": "2027-12-31"
}'

import requests

response = requests.post(
    "https://handelsregister.ai/api/v1/auth/tokens/create",
    headers={"x-api-key": "DEIN_API_SCHLUESSEL"},
    json={
        "token_name": "CRM-Abgleich",
        "abilities": [
            "api:data",
            "account:read"
        ],
        "expires_at": "2027-12-31"
    },
)
data = response.json()

const url = new URL("https://handelsregister.ai/api/v1/auth/tokens/create");

const response = await fetch(url, {
  method: "POST",
  headers: { "x-api-key": "DEIN_API_SCHLUESSEL", "Content-Type": "application/json" },
  body: JSON.stringify({
      "token_name": "CRM-Abgleich",
      "abilities": [
          "api:data",
          "account:read"
      ],
      "expires_at": "2027-12-31"
  }),
});
const data = await response.json();

Parameter
Name	Typ	Beschreibung	Beispiel
token_nameBody	stringPflicht	Ein Name, an dem du das Token wiedererkennst, etwa der Name deiner Anwendung.Grenzen: höchstens 255 Zeichen	`CRM-Abgleich`
abilitiesBody	Liste aus stringoptional	Die Berechtigungen als Liste. Ohne Angabe bekommt das Token `api:data` für die Datenendpunkte und `account:read` für die Konto-Endpunkte. `monitoring:manage` erlaubt Änderungen an Monitoren.Standard: `["*"]`	`["api:data","account:read"]`
expires_atBody	string (date-time)optional	Ablaufdatum in der Zukunft. Ohne Angabe gilt das Token, bis du es widerrufst.	`2027-12-31`

Die Antwort enthält das Token im Feld token, dazu name, abilities, expires_at und created_at. Das Token siehst du nur dieses eine Mal. Speichere es gleich. Ohne expires_at gilt das Token, bis du es widerrufst.

Diese Berechtigungen kann ein Token haben:

Berechtigung
Berechtigung	Bedeutung
api:data	Daten abfragen: Firmenprofile, Personenprofile, Suche & Export, Dokumente und Signals. Diese Endpunkte nehmen jedes gültige Token an.
account:read	Das Konto lesen: Guthaben, Nutzung, Credit-Abo, API-Schlüssel, Monitore und Webhook-Endpoints.
monitoring:manage	Monitore anlegen, ändern, pausieren, fortsetzen und archivieren, Webhook-Endpoints verifizieren und testen, Zustellungen erneut senden.
account:keys	API-Schlüssel und Webhook-Endpoints verwalten. Diese Berechtigung hat nur das Admin-Token.

Mit GET /v1/auth/tokens listest du deine Tokens. DELETE /v1/auth/tokens/{id} widerruft eines, DELETE /v1/auth/tokens alle, das Admin-Token eingeschlossen.

Für diese Endpunkte gilt ein Limit von 10 Anfragen pro Minute. Sie kosten keine Credits.

Admin-Token

Wer Zugänge verwaltet, braucht mehr als einen API-Schlüssel. Nur mit dem Admin-Token kannst du per API Schlüssel anlegen und löschen sowie Webhook-Endpoints einrichten.

Das Admin-Token erstellst du unter Konto › API-Schlüssel im Bereich „Für Entwickler: Schlüssel per API verwalten“. Es gilt ein Jahr. Ein neues Admin-Token ersetzt das alte. Dort kannst du es auch jederzeit widerrufen.

Du schickst es als Bearer-Token mit: Authorization: Bearer DEIN_ADMIN_TOKEN. Es hat die Berechtigungen account:read, account:keys und monitoring:manage.

Aktion
Aktion	API-Schlüssel	Bearer-Token braucht
Konto lesen (alle GET unter `/v1/account`)	ja	`account:read`
Monitore verwalten, Webhook-Endpoints verifizieren und testen, Zustellungen erneut senden	ja	`account:read`, `monitoring:manage`
API-Schlüssel anlegen und löschen	nein, nur mit Admin-Token	`account:keys`
Webhook-Endpoints anlegen, Secret rotieren, aktivieren, deaktivieren und archivieren	nein, nur mit Admin-Token	`account:read`, `account:keys`

Bewahre das Admin-Token getrennt von den Schlüsseln deiner Anwendungen auf. Es gehört nur in Werkzeuge, die Zugänge verwalten.

OAuth für KI-Agenten

ChatGPT, Claude und andere KI-Agenten melden sich per OAuth 2.1 an. Du trägst nur die Server-URL ein, meldest dich bei handelsregister.ai an und stimmst zu. Einen API-Schlüssel musst du dabei nicht kopieren.

Die Server-URL des MCP-Servers lautet https://mcp.handelsregister.ai/mcp. Wie du ChatGPT, Claude und andere Clients einrichtest, steht unter ChatGPT-Plugin und MCP.

Baust du einen eigenen Client, findet er alles Nötige über die Discovery-Dokumente:

Was
Was	Adresse
Metadaten des MCP-Servers (Protected Resource)	`https://mcp.handelsregister.ai/.well-known/oauth-protected-resource`
Metadaten des Autorisierungsservers	`https://handelsregister.ai/.well-known/oauth-authorization-server`
Client registrieren (Dynamic Client Registration)	`POST https://handelsregister.ai/oauth/register`
Anmeldung und Zustimmung	`https://handelsregister.ai/oauth/authorize`
Token holen und erneuern	`POST https://handelsregister.ai/oauth/token`
Token widerrufen	`POST https://handelsregister.ai/oauth/revoke`

Der Ablauf ist der Authorization Code Flow mit PKCE, am besten mit der Methode S256. Clients registrieren sich selbst über die Dynamic Client Registration.

Das Access-Token ist kurz gültig; wie lange, steht in expires_in. Mit dem Scope offline_access bekommt der Client ein Refresh-Token und erneuert den Zugang selbst.

Scope
Scope	Bedeutung
mcp	Die Tools des MCP-Servers nutzen. Das Token gilt auch für die Daten-Endpunkte der API.
api	Die API in deinem Namen nutzen: Daten abfragen und das Konto lesen.
offline_access	Verbunden bleiben, auch wenn du nicht da bist (Refresh-Token).

Fragt ein Client keine Scopes an, bekommt er mcp und offline_access.

Ein OAuth-Token schickst du wie jedes Bearer-Token im Header Authorization. Jede Anfrage damit läuft über dein Konto und dein Guthaben, zu denselben Preisen wie mit API-Schlüssel.

Schlüssel schützen

Wer deinen API-Schlüssel kennt, kann auf deine Kosten Daten abrufen. Behandle ihn wie ein Passwort.

Nutze ihn nur auf deinem Server, nie im Browser oder in einer App, die du verteilst. Dort kann ihn jeder auslesen.
Lege ihn in einer Umgebungsvariablen oder einem Secret-Speicher ab, nicht im Quellcode und nicht in Git.
Schick ihn im Header, nicht in der URL.
Wechsle Schlüssel regelmäßig: neuen Schlüssel anlegen, in der Anwendung tauschen, alten löschen.

Ist ein Schlüssel nach außen gelangt, lösch ihn sofort unter Konto › API-Schlüssel. Ab diesem Moment lehnt die API Anfragen mit ihm ab.

Fehler bei der Anmeldung

Diese Antworten zeigen, dass etwas mit dem Zugang nicht stimmt. Sie kosten nie Credits.

Status
Status	Ursache	Was du tun kannst
400	`api_key` in der URL einer Anfrage an `/v1/account/*`.	Den Schlüssel im Header `x-api-key` schicken.
401	Kein Zugang mitgeschickt, oder Schlüssel bzw. Token sind ungültig, gelöscht oder abgelaufen.	Header prüfen, Schlüssel unter Konto › API-Schlüssel vergleichen.
403	Die E-Mail-Adresse des Kontos ist noch nicht bestätigt.	Den Bestätigungslink aus der Mail öffnen.
403	Dem Token fehlt eine Berechtigung, oder ein API-Schlüssel will Zugänge verwalten.	Ein Token mit der passenden Berechtigung nutzen, für Zugänge das Admin-Token.

1{2  "error": "Unauthorized: Missing or invalid authentication. Please provide a valid API key (via x-api-key header or api_key parameter) or Bearer token."3}

401 · Beispielantwort ohne gültigen Zugang