Administration

API keys and OAuth clients

Create scoped API keys for scripts and CI, register OAuth clients for applications that act on a user's behalf, and revoke access when you're done.

Polylane has two credential types for programmatic access. API keys are for scripts, continuous integration, and headless tools: one key, one workspace, a fixed set of scopes. OAuth clients are for applications that sign users in and call Polylane on their behalf. Both authenticate against the same API.

API keys

Create a key

Open Settings → API Keys in the console and click Create an API key. Give the key a name (at least 4 characters) and toggle on the scopes it needs. The form preselects the scopes your own membership holds, and you can't grant a scope you don't hold yourself: the request fails with a 403.

The key is shown once, at creation. It starts with sk_. Copy it and store it in your secret manager; you can't view it again.

Each key belongs to one workspace. Requests authenticated with a key are authorized against the key's scopes, not the owner's full permissions, so a threads:read-only key can never create a thread.

Scopes

Scopes follow a resource:scope format: threads:read, issues:write, cloud_infra:read, automations:delete, agent_tools:read. The create form lists every scope with a description, or fetch them from the API:

Terminal

curl https://api.polylane.com/v1/scopes \
  -H "x-api-key: sk_xxxxx"

Call the API

Send the key in the x-api-key header:

Terminal

curl https://api.polylane.com/v1/threads/ws_0abc123 \
  -H "x-api-key: sk_xxxxx"

Every endpoint, with its required scopes, is documented in the API reference.

Revoke a key

Delete the key from Settings → API Keys, or through the API:

Terminal

curl -X DELETE https://api.polylane.com/v1/api_keys/ws_0abc123/<key-id> \
  -H "x-api-key: sk_xxxxx"

Deletion is immediate: the next request with the deleted key returns a 401.

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 the oauth_clients:write scope, which workspace admins and owners hold by default.

Register a client

Open Settings → OAuth Clients and click New OAuth client. You provide an application name, a contact email, at least one redirect URI, and at least one scope. Description, website URL, and logo URL are optional.

Creation returns a client ID (starts with oauth_client_) and a client secret.

The client secret is shown once. If you lose it, rotate it from the client's detail page; the old secret stops working.

The authorization flow

Polylane implements the OAuth 2.0 authorization code flow with Proof Key for Code Exchange (PKCE, S256 supported).

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 ?code=.... Exchange it on your backend:

Terminal

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 contains an access_token that expires in 1 hour and a refresh_token.

Call the API as the user

Terminal

curl https://api.polylane.com/v1/threads/ws_0abc123 \
  -H "Authorization: Bearer <access-token>"

Refresh when the access token expires

Use "grant_type": "refresh_token" against the same token endpoint. Refresh tokens are single use: each refresh returns a new one.

Server metadata, including all endpoint URLs, is published at https://api.polylane.com/v1/.well-known/oauth-authorization-server. The provider also exposes /v1/oauth/userinfo and /v1/oauth/introspect.

Revoke tokens and clients

Revoke a token your application holds:

Terminal

curl -X POST https://api.polylane.com/v1/oauth/revoke \
  -H "Content-Type: application/json" \
  -d '{
    "token": "<token>",
    "token_type_hint": "refresh_token",
    "client_id": "<client-id>",
    "client_secret": "<client-secret>"
  }'

token_type_hint accepts refresh_token or access_token; omit it to try both. From the client's detail page you can also rotate the secret or delete the client. Deleting a client stops it from obtaining new tokens; outstanding access tokens expire within the hour.

Coding agents and MCP

You don't need to register an OAuth client to connect a coding agent. The hosted Model Context Protocol server at https://mcp.polylane.com/mcp runs its own OAuth flow with dynamic client registration, and it also accepts an API key. See Platform MCP and CLI authentication.

AI models

Choose which models power your workspace's agents, bring your own provider key, or point Polylane at your own OpenAI-compatible endpoint.

Billing and usage

How Polylane meters credits, what each plan limits, how overage works, and how to change plans.