OAuth 2.0 Client Credentials

Overzicht

De Client Credentials-grant is bedoeld voor server-naar-server-integraties waarbij geen gebruiker aanwezig is: CI-pipelines, cronjobs, backenddiensten en integraties met SaaS-platforms. Je applicatie ruilt een combinatie van client_id en client_secret in voor een kortlevend Bearer-access token.

OAuth of API-sleutels: wanneer gebruik je wat?

1. Maak een OAuth-client aan

Ga naar Studio → Ontwikkelaars-API → OAuth 2.0-clients en klik op OAuth-client aanmaken. Geef de client een duidelijke naam en beperk eventueel de scopes.

2. Vraag een access token op

Stuur een POST-request naar het token-endpoint, met application/x-www-form-urlencoded (de RFC-standaard) of application/json (voor het gemak):

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"
}

Foutmeldingen volgen het formaat van RFC 6749 §5.2. { "error": "invalid_client", "error_description": "…" }

3. Gebruik het token

Stuur het access_token bij elke API-request mee als Bearer-token, precies zoals een API-sleutel:

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

Je applicatie moet het token cachen en pas een nieuw token opvragen als expires_in bijna verstreken is (bijvoorbeeld vernieuwen zodra er minder dan 5 minuten over zijn).

Geldigheid en vernieuwen van tokens

Tokens zijn 1 uur geldig (expires_in: 3600). Er is geen refresh token: vraag gewoon met je clientgegevens een nieuw token op als het huidige verloopt. Omdat dit een flow aan de serverkant is, verlaat het client secret nooit je 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

Met scopes beperk je wat een OAuth-client mag doen. Geef je bij het aanmaken van de client geen scopes op, dan krijgt hij volledige toegang tot de werkruimte (gelijk aan een API-sleutel).

Bekijk de scope-referentie voor de volledige lijst.

Een client intrekken

Als je een client intrekt, worden alle tokens die ervoor zijn uitgegeven direct ongeldig. Lopende requests met zo'n token mislukken met 401 invalid_oauth_token.

Ga naar Studio → Ontwikkelaars-API → OAuth 2.0-clients en klik op Intrekken.