OAuth 2.0 Client Credentials

Vue d'ensemble

L'octroi Client Credentials est conçu pour les intégrations de serveur à serveur, sans utilisateur présent : pipelines CI, tâches planifiées, services backend et intégrations de plateformes SaaS. Votre application échange une paire client_id / client_secret contre un jeton d'accès Bearer de courte durée.

OAuth ou clés d'API : que choisir

1. Créer un client OAuth

Rendez-vous dans Studio → API développeur → Clients OAuth 2.0 et cliquez sur Créer un client OAuth. Donnez-lui un nom explicite et, si besoin, restreignez les portées.

2. Obtenir un jeton d'accès

Envoyez une requête POST au point de terminaison du jeton en application/x-www-form-urlencoded (le standard RFC) ou en application/json (par commodité) :

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

Les erreurs suivent le format RFC 6749 §5.2. { "error": "invalid_client", "error_description": "…" }

3. Utiliser le jeton

Incluez l’access_token comme jeton Bearer dans chaque requête API, exactement comme une clé d'API :

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

Votre application devrait mettre le jeton en cache et n'en redemander un que lorsque expires_in approche (par exemple à moins de 5 minutes restantes).

Durée de vie et renouvellement du jeton

Les jetons sont valables 1 heure (expires_in: 3600). Il n'y a pas de jeton de rafraîchissement : demandez simplement un nouveau jeton avec vos identifiants client à l'expiration. Comme il s'agit d'un flux côté serveur, le secret client ne quitte jamais votre 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;
}

Portées

Les portées permettent de limiter ce qu'un client OAuth peut faire. Si vous n'en spécifiez aucune à la création, le client hérite d'un accès complet à l'espace de travail (équivalent à une clé d'API).

Consultez la référence des portées complète pour la liste intégrale.

Révoquer un client

Révoquer un client invalide immédiatement tous les jetons émis pour lui. Les requêtes en cours utilisant un jeton échoueront avec 401 invalid_oauth_token.

Rendez-vous dans Studio → API développeur → Clients OAuth 2.0 et cliquez sur Révoquer.