Wie richte ich meinen ersten API-Zugang ein (API-Key, Scopes, erste Anfrage)?

Wie richte ich meinen ersten API-Zugang ein (API-Key, Scopes, erste Anfrage)?

Jede Anfrage an REST API Pro braucht einen API-Key. Den erstellst du in wenigen Klicks im Admin-Bereich und legst dabei genau fest, was der Key darf.

🔐 API-Key erstellen

1. Öffne REST API Pro → API Keys und klicke auf API-Key erstellen.
2. Gib dem Key einen sprechenden Namen (z. B. "Zapier-Integration").
3. Wähle die Scopes: In einer Read/Write-Matrix legst du pro Ressource fest, ob der Key nur lesen oder auch schreiben darf. Alternativ gibt es Vollzugriff. Vergib immer nur so viele Rechte wie nötig.
4. Optional: Ablaufdatum (leer = läuft nie ab), IP-Whitelist (kommagetrennte IPs oder CIDR-Bereiche, leer = alle IPs erlaubt) und ein eigenes Rate-Limit pro Minute (leer = globaler Standard).
5. Klicke auf Key generieren.

⚠️ Nur einmal sichtbar

Der Key wird aus Sicherheitsgründen nur als SHA-256-Hash gespeichert und dir genau einmal im Klartext angezeigt. Kopiere ihn sofort und lege ihn sicher ab. Geht er verloren, erstellst du einfach einen neuen und widerrufst den alten. Ein widerrufener Key funktioniert sofort nicht mehr.

📡 Deine erste Anfrage

Authentifiziere dich entweder per Authorization: Bearer oder über den Header X-Api-Key . Den X-Api-Key -Header solltest du nehmen, wenn dein Hoster den Authorization-Header entfernt. So sieht ein einfacher Aufruf aus:

curl 'https://dein-crm.de/rest_api_pro/v1/customers?per_page=5' \ -H 'X-Api-Key: DEIN_API_KEY'

Praktisch zum Testen ist auch der Endpunkt /v1/me , der dir Infos zum aktuellen Key liefert:

curl 'https://dein-crm.de/rest_api_pro/v1/me' \ -H 'X-Api-Key: DEIN_API_KEY'

🎫 Optionale Kurzzeit-Token (JWT)

Du kannst deinen Key gegen ein kurzlebiges JWT eintauschen ( POST /auth/token ) und dieses als Bearer-Token verwenden. Das ist ideal für Browser- oder Mobile-Clients, die niemals den echten Key halten sollen. Die Laufzeit stellst du in den Einstellungen ein.

🚦 Rate-Limit

Jede Antwort enthält X-RateLimit-* -Header, an denen du siehst, wie viele Anfragen dir im aktuellen Fenster noch bleiben. Bei Überschreitung antwortet die API mit HTTP 429. Am schnellsten testest du all das im eingebauten Playground unter API Docs.