API-ключи и OAuth-клиенты
В Polylane два типа учётных данных для программного доступа. API-ключи подходят скриптам, CI и инструментам без браузера: один ключ, одно рабочее пространство, фиксированный набор областей. OAuth-клиенты подходят приложениям, которые выполняют вход пользователей и вызывают Polylane от их имени, и оба типа аутентифицируются в одном и том же API.
API-ключи
Откройте Settings > API Keys в консоли и нажмите Create an API key. Назовите ключ (не меньше 4 символов) и выберите его области: форма заранее отмечает области, которыми обладает ваше членство, а запрос области, которой у вас нет, завершается ошибкой 403. Ключ показывается один раз, начинается с sk_ и больше не может быть просмотрен, поэтому скопируйте его в свой менеджер секретов.
Отправляйте ключ в заголовке x-api-key:
curl https://api.polylane.com/v1/scopes \
-H "x-api-key: sk_xxxxx"
Запросы авторизуются по областям ключа, а не по вашим полным разрешениям. Отзовите ключ на той же странице настроек или запросом DELETE на /v1/api_keys/{workspaceId}/{id}; удалить ключ может его создатель или администратор рабочего пространства.
Области
Область объединяет ресурс и действие, а GET /v1/scopes перечисляет каждую с её описанием. Ниже области, которые чаще всего встречаются в этой документации.
| Область | Описание |
|---|---|
threads:read | Просмотр тредов. |
issues:write | Подтверждение, закрытие или повторный запуск проверок проблем. |
cloud_infra:read | Просмотр узлов и рёбер облачной инфраструктуры. |
autofixes:write | Запись и обновление состояния жизненного цикла автофиксов. |
agent_tools:read | Обнаружение и запуск инструментов агентов только для чтения из внешних клиентов, таких как MCP. |
agent_tools:write | Запуск инструментов агентов с возможностью записи из внешних клиентов, с проверкой безопасности. |
oauth_clients:write | Создание OAuth-клиентов и управление ими. |
analytics:read | Просмотр активности рабочего пространства, популярного содержимого и статистики использования. |
OAuth-клиенты
OAuth-клиент: это приложение, которое вы регистрируете, чтобы оно могло выполнять вход пользователей и вызывать Polylane с областями, которые одобряет каждый пользователь; для управления клиентами нужна область oauth_clients:write. Откройте Settings > OAuth Clients и нажмите New OAuth client: имя и контактный адрес электронной почты показываются на экране согласия, вы добавляете URI перенаправления и области, которые клиент может запрашивать, а описание, сайт и логотип необязательны. Создание возвращает идентификатор клиента, начинающийся с oauth_client_, и секрет клиента, показываемый один раз; если вы потеряли секрет, выполните Rotate на странице клиента, и предыдущий секрет немедленно перестанет работать.
Процесс авторизации
Polylane реализует поток кода авторизации OAuth 2.0 с PKCE (S256).
Отправьте пользователя на страницу согласия
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>
URI перенаправления должен точно совпадать с одним из зарегистрированных, а каждая запрошенная область должна быть одной из выданных клиенту.
Обменяйте код на токены
После одобрения пользователем Polylane перенаправляет на ваш колбэк с code. Обменяйте его на своём бэкенде:
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>"}'
Ответ содержит access_token, который истекает через час, и refresh_token.
Вызывайте API от имени пользователя
curl https://api.polylane.com/v1/scopes \
-H "Authorization: Bearer <access-token>"
Обновляйте токен, когда токен доступа истекает
Отправьте grant_type refresh_token на тот же эндпоинт токенов. Токены обновления одноразовые: каждое обновление возвращает замену.
Метаданные сервера, включая URL каждого эндпоинта, публикуются по адресу https://api.polylane.com/v1/.well-known/oauth-authorization-server, а провайдер также предоставляет /v1/oauth/userinfo и /v1/oauth/introspect. Отзовите токен, которым владеет ваше приложение, запросом POST на /v1/oauth/revoke с токеном и учётными данными вашего клиента, указав в token_type_hint значение access_token или refresh_token или опустив его, чтобы попробовать оба. Удаление клиента с его страницы не даёт ему начинать новые авторизации.
Кодинг-агенты
Для подключения кодинг-агента OAuth-клиент не нужен. Размещённый MCP-сервер по адресу https://mcp.polylane.com/mcp выполняет собственный поток OAuth с динамической регистрацией клиентов и также принимает API-ключ; см. MCP-сервер платформы.
См. также
- MCP-сервер платформы: подключите агента редактора без регистрации клиента.
- Аутентификация CLI: войдите в CLI через браузер, код устройства или API-ключ.
- Справочник API: каждый эндпоинт и области, которые он требует.