Chaves de API e clientes OAuth
O Polylane tem dois tipos de credencial para acesso programático. Chaves de API convêm a scripts, CI e ferramentas sem interface gráfica: uma chave, um workspace, um conjunto fixo de escopos. Clientes OAuth convêm a aplicações que fazem login de usuários e chamam o Polylane em nome deles, e ambos autenticam contra a mesma API.
Chaves de API
Abra Settings > API Keys no console e clique em Create an API key. Dê um nome à chave (pelo menos 4 caracteres) e escolha os escopos: o formulário pré-seleciona os escopos que a sua própria associação tem, e uma requisição por um escopo que você não tem falha com um 403. A chave é mostrada uma vez, começa com sk_ e não pode ser vista de novo, então copie-a para o seu gerenciador de segredos.
Envie a chave no cabeçalho x-api-key:
curl https://api.polylane.com/v1/scopes \
-H "x-api-key: sk_xxxxx"
As requisições são autorizadas contra os escopos da chave, não contra as suas permissões completas. Revogue uma chave na mesma página de configurações ou com um DELETE em /v1/api_keys/{workspaceId}/{id}; quem criou a chave ou um admin do workspace pode excluí-la.
Escopos
Os escopos pareiam um recurso com uma ação, e GET /v1/scopes lista todos com sua descrição. Estes são os escopos que você encontrará com mais frequência nesta documentação.
| Escopo | Descrição |
|---|---|
threads:read | Ver threads. |
issues:write | Reconhecer, resolver ou reexecutar verificações de issues. |
cloud_infra:read | Ver nós e arestas da infraestrutura de nuvem. |
autofixes:write | Registrar e atualizar o estado do ciclo de vida de autofixes. |
agent_tools:read | Descobrir e executar ferramentas de agente somente leitura a partir de clientes externos, como MCP. |
agent_tools:write | Executar ferramentas de agente com capacidade de escrita a partir de clientes externos, sujeitas a revisão de segurança. |
oauth_clients:write | Criar e gerenciar clientes OAuth. |
analytics:read | Ver a atividade do workspace, o conteúdo popular e as estatísticas de uso. |
Clientes OAuth
Um cliente OAuth é uma aplicação que você registra para que ela possa fazer login de usuários e chamar o Polylane com os escopos que cada usuário aprova; gerenciar clientes exige oauth_clients:write. Abra Settings > OAuth Clients e clique em New OAuth client: o nome e o e-mail de contato aparecem na tela de consentimento, você adiciona as URIs de redirecionamento e os escopos que o cliente pode solicitar, e descrição, site e logo são opcionais. A criação retorna um ID de cliente que começa com oauth_client_ e um segredo de cliente mostrado uma vez; se você perder o segredo, use Rotate na página do cliente e o segredo anterior deixa de funcionar imediatamente.
O fluxo de autorização
O Polylane implementa o fluxo de código de autorização do OAuth 2.0 com PKCE (S256).
Envie o usuário para a página de consentimento
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>
A URI de redirecionamento deve corresponder exatamente a uma que você registrou, e todo escopo solicitado deve ser um que o cliente recebeu.
Troque o código por tokens
Depois que o usuário aprova, o Polylane redireciona para o seu callback com um code. Troque-o no seu 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>"}'
A resposta carrega um access_token que expira após uma hora e um refresh_token.
Chame a API como o usuário
curl https://api.polylane.com/v1/scopes \
-H "Authorization: Bearer <access-token>"
Renove quando o access token expirar
Envie grant_type refresh_token ao mesmo endpoint de token. Os refresh tokens são de uso único: cada renovação retorna um substituto.
Os metadados do servidor, incluindo toda URL de endpoint, são publicados em https://api.polylane.com/v1/.well-known/oauth-authorization-server, e o provedor também expõe /v1/oauth/userinfo e /v1/oauth/introspect. Revogue um token que a sua aplicação possui com um POST em /v1/oauth/revoke carregando o token e as credenciais do seu cliente, com token_type_hint definido como access_token ou refresh_token, ou omitido para tentar ambos. Excluir um cliente na página dele o impede de iniciar novas autorizações.
Agentes de programação
Você não precisa de um cliente OAuth para conectar um agente de programação. O servidor MCP hospedado em https://mcp.polylane.com/mcp executa seu próprio fluxo OAuth com registro dinâmico de cliente e também aceita uma chave de API; veja Servidor MCP da plataforma.
Relacionado
- Servidor MCP da plataforma para conectar um agente de editor sem registrar um cliente.
- Autenticação da CLI para fazer login na CLI com um navegador, um código de dispositivo ou uma chave de API.
- Referência da API para todo endpoint e os escopos que ele exige.