OAuth 2.0 Client Credentials

Überblick

Der Client-Credentials-Grant ist für Server-zu-Server-Integrationen gedacht, bei denen keine Person anwesend ist: CI-Pipelines, Cron-Jobs, Backend-Dienste und SaaS-Plattform-Integrationen. Deine Anwendung tauscht ein Paar aus client_id und client_secret gegen ein kurzlebiges Bearer-Access-Token.

OAuth oder API-Schlüssel?

1. OAuth-Client anlegen

Geh zu Studio → Entwickler-API → OAuth-2.0-Clients und klick auf OAuth-Client erstellen. Gib ihm einen sprechenden Namen und schränke bei Bedarf die Scopes ein.

2. Access-Token holen

Sende eine POST-Anfrage an den Token-Endpunkt, entweder als application/x-www-form-urlencoded (RFC-Standard) oder als application/json (bequemer):

curl -X POST https://pollslive.com/api/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials&client_id=plv_cid_…&client_secret=plv_cs_…&scope=polls:read polls:write"

curl -X POST https://pollslive.com/api/oauth/token \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "client_credentials",
    "client_id": "plv_cid_…",
    "client_secret": "plv_cs_…",
    "scope": "polls:read polls:write"
  }'

{
  "access_token": "plv_oauth_…",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "polls:read polls:write"
}

Fehler folgen dem Format RFC 6749 §5.2. { "error": "invalid_client", "error_description": "…" }

3. Token verwenden

Gib das access_token bei jeder API-Anfrage als Bearer-Token mit, genau wie einen API-Schlüssel:

curl https://pollslive.com/api/v1/polls \
  -H "Authorization: Bearer plv_oauth_…"

Deine Anwendung sollte das Token zwischenspeichern und erst dann ein neues anfordern, wenn expires_in zur Neige geht (z. B. bei weniger als 5 Minuten Restlaufzeit).

Token-Laufzeit & Erneuerung

Tokens sind 1 Stunde gültig (expires_in: 3600). Ein Refresh-Token gibt es nicht. Fordere bei Ablauf einfach mit deinen Client-Credentials ein neues an. Da es ein serverseitiger Flow ist, verlässt das Client-Secret nie dein Backend.

let token = null;
let expiresAt = 0;

async function getToken() {
  if (token && Date.now() < expiresAt - 5 * 60 * 1000) return token;

  const res = await fetch("https://pollslive.com/api/oauth/token", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      grant_type: "client_credentials",
      client_id: process.env.OAUTH_CLIENT_ID,
      client_secret: process.env.OAUTH_CLIENT_SECRET,
    }),
  });
  const data = await res.json();
  token = data.access_token;
  expiresAt = Date.now() + data.expires_in * 1000;
  return token;
}

Scopes

Mit Scopes begrenzt du, was ein OAuth-Client tun darf. Gibst du beim Anlegen keine an, erbt der Client vollen Workspace-Zugriff (gleichbedeutend mit einem API-Schlüssel).

Die vollständige Liste steht in der Scope-Referenz.

Client widerrufen

Ein Widerruf macht alle für diesen Client ausgestellten Tokens sofort ungültig. Laufende Anfragen mit einem solchen Token scheitern mit 401 invalid_oauth_token.

Geh zu Studio → Entwickler-API → OAuth-2.0-Clients und klick auf Widerrufen.