OAuth 2.0 Client Credentials

Resumen

La concesión Client Credentials está pensada para integraciones de servidor a servidor sin ninguna persona presente: pipelines de CI, tareas programadas, servicios de backend e integraciones de plataformas SaaS. Tu aplicación intercambia un par client_id / client_secret por un token de acceso Bearer de corta duración.

Cuándo usar OAuth y cuándo claves de API

1. Crear un cliente OAuth

Ve a Studio → API para desarrolladores → Clientes OAuth 2.0 y pulsa Crear cliente OAuth. Dale un nombre descriptivo y, si quieres, acota los ámbitos.

2. Obtener un token de acceso

Envía una petición POST al endpoint de token usando application/x-www-form-urlencoded (el estándar del RFC) o application/json (por comodidad):

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

Los errores siguen el formato RFC 6749 §5.2. { "error": "invalid_client", "error_description": "…" }

3. Usar el token

Incluye el access_token como token Bearer en cada petición a la API, exactamente igual que una clave de API:

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

Tu aplicación debería cachear el token y pedir otro solo cuando se acerque expires_in (por ejemplo, renovarlo cuando queden menos de 5 minutos).

Duración y renovación del token

Los tokens son válidos durante 1 hora (expires_in: 3600). No hay token de actualización: basta con pedir uno nuevo con las credenciales del cliente cuando caduque el actual. Como es un flujo de servidor, el secreto del cliente nunca sale de tu 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;
}

Ámbitos

Los ámbitos te permiten limitar lo que puede hacer un cliente OAuth. Si no especificas ninguno al crear el cliente, hereda acceso completo al espacio de trabajo (equivalente a una clave de API).

Consulta la referencia de ámbitos completa para ver la lista entera.

Revocar un cliente

Revocar un cliente invalida de inmediato todos los tokens emitidos para él. Las peticiones en curso que usen un token fallarán con 401 invalid_oauth_token.

Ve a Studio → API para desarrolladores → Clientes OAuth 2.0 y pulsa Revocar.