Ключі 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: назва та контактна електронна пошта з'являються на екрані згоди, ви додаєте redirect URI та області дії, які клієнт може запитувати, а опис, вебсайт і логотип необов'язкові. Створення повертає ідентифікатор клієнта, що починається з oauth_client_, і секрет клієнта, який показується один раз; якщо ви втратите секрет, скористайтеся Rotate на сторінці клієнта, і попередній секрет негайно перестане працювати.
Процес авторизації
Polylane реалізує процес OAuth 2.0 authorization code з 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>
Redirect URI має точно збігатися з одним із зареєстрованих, а кожна запитана область дії має бути серед наданих клієнту.
Обміняйте код на токени
Після схвалення користувачем Polylane перенаправляє на ваш callback з 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: кожний ендпоінт і області дії, яких він вимагає.