Claves de API y clientes OAuth
Polylane tiene dos tipos de credencial para el acceso programático. Las claves de API sirven para scripts, CI y herramientas sin interfaz gráfica: una clave, un espacio de trabajo, un conjunto fijo de ámbitos. Los clientes OAuth sirven para aplicaciones que inician sesión a los usuarios y llaman a Polylane en su nombre, y ambos se autentican contra la misma API.
Claves de API
Abre Settings > API Keys en la consola y haz clic en Create an API key. Dale un nombre a la clave (al menos 4 caracteres) y elige sus ámbitos: el formulario preselecciona los ámbitos que tiene tu propia membresía, y una petición de un ámbito que no tienes falla con un 403. La clave se muestra una sola vez, empieza por sk_ y no se puede volver a ver, así que cópiala en tu gestor de secretos.
Envía la clave en la cabecera x-api-key:
curl https://api.polylane.com/v1/scopes \
-H "x-api-key: sk_xxxxx"
Las peticiones se autorizan contra los ámbitos de la clave, no contra todos tus permisos. Revoca una clave desde la misma página de ajustes o con un DELETE a /v1/api_keys/{workspaceId}/{id}; quien creó la clave o un administrador del espacio de trabajo puede eliminarla.
Ámbitos
Los ámbitos emparejan un recurso con una acción, y GET /v1/scopes lista cada uno con su descripción. Estos son los ámbitos que encontrarás con más frecuencia en esta documentación.
| Ámbito | Descripción |
|---|---|
threads:read | Ver hilos. |
issues:write | Reconocer, resolver o volver a ejecutar las comprobaciones de un issue. |
cloud_infra:read | Ver los nodos y aristas de la infraestructura de nube. |
autofixes:write | Registrar y actualizar el estado del ciclo de vida de un autofix. |
agent_tools:read | Descubrir y ejecutar herramientas de agente de solo lectura desde clientes externos como MCP. |
agent_tools:write | Ejecutar herramientas de agente con capacidad de escritura desde clientes externos, sujetas a revisión de seguridad. |
oauth_clients:write | Crear y gestionar clientes OAuth. |
analytics:read | Ver la actividad del espacio de trabajo, el contenido popular y las estadísticas de uso. |
Clientes OAuth
Un cliente OAuth es una aplicación que registras para que pueda iniciar sesión a los usuarios y llamar a Polylane con los ámbitos que cada usuario aprueba; gestionar clientes requiere oauth_clients:write. Abre Settings > OAuth Clients y haz clic en New OAuth client: el nombre y el correo de contacto aparecen en la pantalla de consentimiento, añades las URI de redirección y los ámbitos que el cliente puede solicitar, y la descripción, el sitio web y el logotipo son opcionales. La creación devuelve un ID de cliente que empieza por oauth_client_ y un secreto de cliente que se muestra una sola vez; si pierdes el secreto, rótalo con Rotate desde la página del cliente y el secreto anterior deja de funcionar de inmediato.
El flujo de autorización
Polylane implementa el flujo de código de autorización de OAuth 2.0 con PKCE (S256).
Envía al usuario a la página de consentimiento
https://console.polylane.com/oauth/<client-id>
?client_id=<client-id>
&redirect_uri=https://example.com/callback
&scope=threads:read%20issues:read
&code_challenge=<challenge>
&code_challenge_method=S256
&state=<random-state>
La URI de redirección debe coincidir exactamente con una que hayas registrado, y cada ámbito solicitado debe ser uno concedido al cliente.
Intercambia el código por tokens
Cuando el usuario aprueba, Polylane redirige a tu callback con un code. Intercámbialo en tu backend:
curl -X POST https://api.polylane.com/v1/oauth/token \
-H "Content-Type: application/json" \
-d '{"grant_type": "authorization_code", "code": "<code>",
"redirect_uri": "https://example.com/callback",
"client_id": "<client-id>", "client_secret": "<client-secret>",
"code_verifier": "<verifier>"}'
La respuesta lleva un access_token que caduca al cabo de una hora y un refresh_token.
Llama a la API como el usuario
curl https://api.polylane.com/v1/scopes \
-H "Authorization: Bearer <access-token>"
Renueva cuando el token de acceso caduque
Envía por POST grant_type refresh_token al mismo endpoint de tokens. Los tokens de renovación son de un solo uso: cada renovación devuelve un sustituto.
Los metadatos del servidor, incluida la URL de cada endpoint, se publican en https://api.polylane.com/v1/.well-known/oauth-authorization-server, y el proveedor también expone /v1/oauth/userinfo y /v1/oauth/introspect. Revoca un token que tenga tu aplicación con un POST a /v1/oauth/revoke que lleve el token y las credenciales de tu cliente, con token_type_hint puesto en access_token o refresh_token, u omitido para probar ambos. Eliminar un cliente desde su página impide que inicie nuevas autorizaciones.
Agentes de programación
No necesitas un cliente OAuth para conectar un agente de programación. El servidor MCP alojado en https://mcp.polylane.com/mcp ejecuta su propio flujo OAuth con registro dinámico de clientes y también acepta una clave de API; consulta Servidor MCP de la plataforma.
Relacionado
- Servidor MCP de la plataforma para conectar el agente de un editor sin registrar un cliente.
- Autenticación de la CLI para iniciar sesión en la CLI con un navegador, un código de dispositivo o una clave de API.
- Referencia de la API para cada endpoint y los ámbitos que requiere.