Schnittstelle für Entwickler

Diese Seite bringt dich in rund fünf Minuten zum ersten erfolgreichen Aufruf. Die vollständige Referenz listet jede Operation mit Parametern, Beispielantwort und möglichen Fehlern; die maschinenlesbare Fassung liegt unter openapi.v1.json (OpenAPI 3.1, aus demselben Code erzeugt wie diese Seiten).

Voraussetzungen

Die Schnittstelle ist Teil des Team- und des Enterprise-Pakets. Ein Administrator oder der Inhaber des Teams legt den ersten Schlüssel unter Team → Schnittstellen in der App an; das braucht das Teamrecht schnittstellen (standardmäßig nur beim Inhaber, von dort aus erteilbar).

Schnellstart

curl https://app.sip.coach/api/public/v1/me \
  -H "Authorization: Bearer sipk_live_ab12cd34_…"

import httpx

antwort = httpx.get(
    "https://app.sip.coach/api/public/v1/me",
    headers={"Authorization": "Bearer sipk_live_ab12cd34_…"},
)
print(antwort.json())

const res = await fetch("https://app.sip.coach/api/public/v1/me", {
  headers: { Authorization: "Bearer sipk_live_ab12cd34_…" },
});
console.log(await res.json());

<?php
$context = stream_context_create(["http" => ["header" =>
    "Authorization: Bearer sipk_live_ab12cd34_…"]]);
$antwort = file_get_contents("https://app.sip.coach/api/public/v1/me", false, $context);
echo $antwort;

{
  "tenant_id": "6a9c3e3e-9b8e-4b7b-9e9d-2b7b1a2c3d4e",
  "kind": "team",
  "scopes": [
    "users:read",
    "trainings:read",
    "evaluations:read"
  ],
  "rate_limit_per_min": 600,
  "privacy": {
    "member_detail_enabled": true
  }
}

Authentifizierung

Jede Anfrage trägt den Schlüssel im Kopf Authorization: Bearer sipk_live_<Präfix>_<Geheimteil>. Der Schlüssel gehört dem Team, nicht einer Person; seine Scopes stehen bei der Erzeugung fest (eine Erweiterung braucht einen neuen Schlüssel). Widerruf wirkt sofort, eine Rotation überlappt den alten und den neuen Schlüssel für eine wählbare Frist.

Die Oberfläche bietet beim Anlegen zusätzlich die Vorlagen „Nur lesen" (alle :read-Scopes) und „Lesen und Zuweisungen" (zusätzlich assignments:write) an, oder eine eigene Auswahl aus der Tabelle oben.

Mandant und Rechte

Der Mandant steht fest, sobald der Schlüssel erzeugt ist — kein Aufruf nennt eine Team-Kennung, weder im Pfad noch im Körper. Eine fremde Kennung liefert 404, genau wie eine erfundene: ob sie nie existiert hat oder einem anderen Team gehört, ist von außen nicht unterscheidbar.

Fehler

Jede Fehlerantwort folgt RFC 9457 (application/problem+json). code ist stabil und wird nie übersetzt; title richtet sich nach Accept-Language (de oder en).

{
  "type": "https://sip.coach/entwickler/api/fehler#insufficient_scope",
  "title": "Insufficient scope",
  "status": 403,
  "code": "insufficient_scope",
  "detail": "scope 'assignments:write' required",
  "request_id": "a7e8b2c1-4d3e-4f5a-9b6c-7d8e9f0a1b2c",
  "required_scope": "assignments:write"
}

Jeder Code mit Erklärung: Fehlercodes.

Grenzwerte und Idempotenz

120 Anfragen pro Minute je Schlüssel, zusätzlich eine je Mandant einstellbare Grenze (Vorgabe 600/Minute) — es gilt immer die engere der beiden. Jede Antwort trägt RateLimit-Limit, RateLimit-Remaining und RateLimit-Reset.

POST-Aufrufe akzeptieren einen Kopf Idempotency-Key (bis zu 100 Zeichen, 24 Stunden gültig): derselbe Schlüssel mit demselben Körper liefert die erste Antwort erneut, ohne die Aktion ein zweites Mal auszuführen; derselbe Schlüssel mit einem anderen Körper liefert 422 idempotency_mismatch.

Seitenteilung

Listenrouten (z. B. GET /users, GET /assignments) nehmen ?limit= (Vorgabe 50, höchstens 200) und ?cursor= entgegen und antworten mit einem Feld data (die Liste) und next_cursor. next_cursor ist ein undurchsichtiger Wert — nicht als Seitenzahl oder Versatz interpretieren, nur unverändert an den nächsten Aufruf zurückgeben; null heißt: keine weitere Seite.

{
  "data": [
    "…"
  ],
  "next_cursor": "eyJpZCI6ICI5ZjJhLi4uIn0="
}

Versionierung

Pfadversion v1. Innerhalb von v1 nur anfügende Änderungen (neue Felder, neue Routen, neue Ereignistypen) — ignoriere unbekannte Felder in der Antwort. Eine brechende Änderung erscheint als v2 neben v1, mindestens zwölf Monate parallel, angekündigt über die Kopfzeilen Deprecation/Sunset und eine Mail an jeden Administrator mit aktivem Schlüssel.

Datenschutz

Die Datenschutzschalter des Teams gelten für die Schnittstelle genauso wie für die Oberfläche. Ist member_detail_enabled aus, liefern personenbezogene Routen nur Aggregate oder 403 privacy_restricted, und Webhook-Körper enthalten weder Punktzahl noch user_id.

CRM-Verbindungen

Ein verbundenes CRM-System wird über die Oberfläche eingerichtet, unter Team → CRM-Verbindungen — nicht über diese Schnittstelle. Sobald eine Verbindung aktiv ist, liefert GET /crm/deals die synchronisierten Deals und GET /crm/objections den Einwandkatalog des Teams; beide Routen sind nur lesend, seitenweise wie jede andere Listenroute.

Weiter von hier