Übersicht über die ClearPolicy-REST-API

Die ClearPolicy-REST-API ermöglicht dir den programmgesteuerten Zugriff auf die Personen, Gruppen, Dokumente und Bestätigungsanfragen deiner Organisation. Alle Endpunkte kommunizieren über HTTPS und geben JSON zurück.

Basis-URL

https://api.clearpolicy.app/api/v1

Das API-Pfadpräfix (/api/v1) ist in jeder Anfrage-URL enthalten. Die aktuelle und einzige Version ist v1.

Authentifizierung

Alle Endpunkte erfordern ein gültiges API-Bearer-Token. Übergib das Token im Authorization-Header:

Authorization: Bearer YOUR_ACCESS_TOKEN

Siehe Authentifizierung für Anweisungen zum Erstellen eines Tokens.

Deine Organisation muss ein aktives Abonnement haben oder sich innerhalb des Testzeitraums befinden. Wenn dein Test abgelaufen oder dein Abonnement inaktiv ist, geben alle API-Anfragen eine Antwort 402 Payment Required zurück.

Zugriff nach Rolle

Der API-Zugriff folgt deiner Rolle in ClearPolicy. Eigentümer und Administratoren der Organisation können API-Tokens erstellen und die Endpunkte für Personen, Gruppen, Dokumente und Bestätigungsanfragen nutzen. Tokens, die an Gruppenleitende gebunden sind, können GET /me verwenden, um den Token und die Organisation zu bestätigen, aber andere REST-API-Endpunkte geben 403 Forbidden zurück.

Antwortformat

Alle Antworten sind JSON. Erfolgreiche Antworten geben die angeforderte Ressource oder Sammlung direkt im Antwortkörper zurück.

IDs

Alle Ressourcen-IDs sind ULIDs — lexikografisch sortierbare String-Bezeichner. Sie werden als Kleinbuchstabenzeichenfolgen dargestellt, zum Beispiel:

01kg82xqfx6fvr046d15hnfmjv

Paginierung

Listen-Endpunkte geben paginierte Ergebnisse zurück. Die Antwort enthält ein data-Array zusammen mit links- und meta-Objekten:

{
  "data": [...],
  "links": {
    "first": "https://api.clearpolicy.app/api/v1/people?page=1",
    "last": "https://api.clearpolicy.app/api/v1/people?page=5",
    "prev": null,
    "next": "https://api.clearpolicy.app/api/v1/people?page=2"
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 5,
    "per_page": 25,
    "to": 25,
    "total": 120
  }
}

Verwende die Abfrageparameter page und per_page, um durch die Ergebnisse zu navigieren. per_page akzeptiert Werte zwischen 1 und 100, der Standardwert ist 25.

Fehler

Fehler geben JSON mit einem error-Feld zurück, das das Problem beschreibt:

{
  "error": "Person not found."
}

Gängige HTTP-Statuscodes:

Status	Bedeutung
`200 OK`	Anfrage erfolgreich.
`201 Created`	Ressource erfolgreich erstellt.
`400 Bad Request`	Die Anfrage war ungültig (z. B. Dokument nicht veröffentlicht).
`401 Unauthorized`	Zugriffstoken fehlt oder ist ungültig.
`402 Payment Required`	Der Test deiner Organisation ist abgelaufen oder das Abonnement ist inaktiv. Besuche deine Abrechnungsseite, um zu abonnieren.
`403 Forbidden`	Token verfügt nicht über die erforderlichen Berechtigungen.
`404 Not Found`	Die angeforderte Ressource existiert in deiner Organisation nicht.
`422 Unprocessable Entity`	Validierung fehlgeschlagen — überprüfe die Anfrageparameter.
`429 Too Many Requests`	Ratenlimit überschritten — warte und versuche es erneut.

Ratenbegrenzung

Jedes API-Token ist auf 60 Anfragen pro Minute begrenzt. Die Limits gelten pro Token, nicht pro Organisation — mehrere Tokens haben jeweils ihr eigenes Kontingent. Wenn du das Limit überschreitest, gibt die API 429 Too Many Requests zurück. Antworten enthalten die Header Retry-After und X-RateLimit-*, damit du erkennst, wann du es erneut versuchen kannst. Verwende beim Wiederholen ein exponentielles Backoff.

​Basis-URL

​Authentifizierung

​Zugriff nach Rolle

​Antwortformat

​IDs

​Paginierung

​Fehler

​Ratenbegrenzung

Basis-URL

Authentifizierung

Zugriff nach Rolle

Antwortformat

IDs

Paginierung

Fehler

Ratenbegrenzung