API keys and OAuth clients
Polylane has two credential types for programmatic access. API keys suit scripts, CI and headless tools: one key, one workspace, a fixed set of scopes. OAuth clients suit applications that sign users in and call Polylane on their behalf, and both authenticate against the same API.
API keys
Open Settings > API Keys in the console and click Create an API key. Name the key (at least 4 characters) and pick its scopes: the form preselects the scopes your own membership holds, and a request for a scope you do not hold fails with a 403. The key is shown once, starts with sk_ and cannot be viewed again, so copy it into your secret manager.
Send the key in the x-api-key header:
curl https://api.polylane.com/v1/scopes \
-H "x-api-key: sk_xxxxx"
Requests are authorized against the key's scopes, not your full permissions. Revoke a key from the same settings page or with a DELETE to /v1/api_keys/{workspaceId}/{id}; the key's creator or a workspace admin can delete it.
Scopes
Scopes pair a resource with an action, and GET /v1/scopes lists every one with its description. These are the scopes you will meet most often across these docs.
| Scope | Description |
|---|---|
threads:read | View threads. |
issues:write | Acknowledge, resolve or rerun issue checks. |
cloud_infra:read | View cloud infrastructure nodes and edges. |
autofixes:write | Record and update autofix lifecycle state. |
agent_tools:read | Discover and run read-only agent tools from external clients such as MCP. |
agent_tools:write | Run write-capable agent tools from external clients, subject to safety review. |
oauth_clients:write | Create and manage OAuth clients. |
analytics:read | View workspace activity, popular content and usage statistics. |
OAuth clients
An OAuth client is an application you register so it can sign users in and call Polylane with the scopes each user approves; managing clients requires oauth_clients:write. Open Settings > OAuth Clients and click New OAuth client: the name and contact email appear on the consent screen, you add the redirect URIs and the scopes the client may request, and description, website and logo are optional. Creation returns a client ID starting with oauth_client_ and a client secret shown once; if you lose the secret, Rotate it from the client's page and the previous secret stops working immediately.
The authorization flow
Polylane implements the OAuth 2.0 authorization code flow with PKCE (S256).
Send the user to the consent page
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>
The redirect URI must exactly match one you registered, and every requested scope must be one the client was granted.
Exchange the code for tokens
After the user approves, Polylane redirects to your callback with a code. Exchange it on your 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>"}'
The response carries an access_token that expires after one hour and a refresh_token.
Call the API as the user
curl https://api.polylane.com/v1/scopes \
-H "Authorization: Bearer <access-token>"
Refresh when the access token expires
Post grant_type refresh_token to the same token endpoint. Refresh tokens are single use: each refresh returns a replacement.
Server metadata, including every endpoint URL, is published at https://api.polylane.com/v1/.well-known/oauth-authorization-server, and the provider also exposes /v1/oauth/userinfo and /v1/oauth/introspect. Revoke a token your application holds with a POST to /v1/oauth/revoke carrying the token and your client credentials, with token_type_hint set to access_token or refresh_token, or omitted to try both. Deleting a client from its page stops it from starting further authorizations.
Coding agents
You do not need an OAuth client to connect a coding agent. The hosted MCP server at https://mcp.polylane.com/mcp runs its own OAuth flow with dynamic client registration and also accepts an API key; see Platform MCP server.
Related
- Platform MCP server to connect an editor agent without registering a client.
- CLI authentication to sign the CLI in with a browser, a device code or an API key.
- API reference for every endpoint and the scopes it requires.