Chiavi API e client OAuth
Polylane ha due tipi di credenziale per l'accesso programmatico. Le chiavi API sono adatte a script, CI e strumenti headless: una chiave, un workspace, un insieme fisso di scope. I client OAuth sono adatti alle applicazioni che fanno accedere gli utenti e chiamano Polylane per loro conto, ed entrambi si autenticano sulla stessa API.
Chiavi API
Apri Settings > API Keys nella console e fai clic su Create an API key. Assegna un nome alla chiave (almeno 4 caratteri) e scegli i suoi scope: il modulo preseleziona gli scope che la tua stessa iscrizione possiede, e una richiesta per uno scope che non possiedi fallisce con un 403. La chiave viene mostrata una sola volta, inizia con sk_ e non può essere visualizzata di nuovo, quindi copiala nel tuo gestore di secret.
Invia la chiave nell'header x-api-key:
curl https://api.polylane.com/v1/scopes \
-H "x-api-key: sk_xxxxx"
Le richieste vengono autorizzate in base agli scope della chiave, non ai tuoi permessi completi. Revoca una chiave dalla stessa pagina delle impostazioni o con una DELETE su /v1/api_keys/{workspaceId}/{id}; chi ha creato la chiave o un admin del workspace può eliminarla.
Scope
Gli scope abbinano una risorsa a un'azione, e GET /v1/scopes li elenca tutti con la loro descrizione. Questi sono gli scope che incontrerai più spesso in questa documentazione.
| Scope | Descrizione |
|---|---|
threads:read | Vedere i thread. |
issues:write | Prendere in carico, risolvere o rieseguire i controlli delle issue. |
cloud_infra:read | Vedere nodi e archi dell'infrastruttura cloud. |
autofixes:write | Registrare e aggiornare lo stato del ciclo di vita degli autofix. |
agent_tools:read | Scoprire ed eseguire strumenti degli agenti in sola lettura da client esterni come MCP. |
agent_tools:write | Eseguire strumenti degli agenti con capacità di scrittura da client esterni, soggetti a revisione di sicurezza. |
oauth_clients:write | Creare e gestire client OAuth. |
analytics:read | Vedere l'attività del workspace, i contenuti popolari e le statistiche di utilizzo. |
Client OAuth
Un client OAuth è un'applicazione che registri perché possa far accedere gli utenti e chiamare Polylane con gli scope che ogni utente approva; gestire i client richiede oauth_clients:write. Apri Settings > OAuth Clients e fai clic su New OAuth client: il nome e l'email di contatto compaiono nella schermata di consenso, aggiungi i redirect URI e gli scope che il client può richiedere, e descrizione, sito web e logo sono facoltativi. La creazione restituisce un client ID che inizia con oauth_client_ e un client secret mostrato una sola volta; se perdi il secret, ruotalo con Rotate dalla pagina del client e il secret precedente smette di funzionare immediatamente.
Il flusso di autorizzazione
Polylane implementa il flusso OAuth 2.0 authorization code con PKCE (S256).
Invia l'utente alla pagina di consenso
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>
Il redirect URI deve corrispondere esattamente a uno di quelli che hai registrato, e ogni scope richiesto deve essere uno di quelli concessi al client.
Scambia il codice con i token
Dopo l'approvazione dell'utente, Polylane reindirizza al tuo callback con un code. Scambialo sul tuo 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 risposta contiene un access_token che scade dopo un'ora e un refresh_token.
Chiama l'API come l'utente
curl https://api.polylane.com/v1/scopes \
-H "Authorization: Bearer <access-token>"
Rinnova quando l'access token scade
Invia con POST grant_type refresh_token allo stesso endpoint dei token. I refresh token sono monouso: ogni rinnovo ne restituisce uno nuovo.
I metadati del server, compresi tutti gli URL degli endpoint, sono pubblicati su https://api.polylane.com/v1/.well-known/oauth-authorization-server, e il provider espone anche /v1/oauth/userinfo e /v1/oauth/introspect. Revoca un token in possesso della tua applicazione con una POST su /v1/oauth/revoke che porta il token e le credenziali del tuo client, con token_type_hint impostato su access_token o refresh_token, oppure omesso per provarli entrambi. Eliminare un client dalla sua pagina gli impedisce di avviare ulteriori autorizzazioni.
Agenti di coding
Non ti serve un client OAuth per collegare un agente di coding. Il server MCP ospitato su https://mcp.polylane.com/mcp esegue il proprio flusso OAuth con registrazione dinamica dei client e accetta anche una chiave API; vedi Server MCP della piattaforma.
Correlati
- Server MCP della piattaforma per collegare l'agente di un editor senza registrare un client.
- Autenticazione della CLI per far accedere la CLI con un browser, un codice dispositivo o una chiave API.
- Riferimento API per ogni endpoint e gli scope che richiede.