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"
요청은 사용자의 전체 권한이 아니라 키의 스코프에 대해 인가됩니다. 같은 설정 페이지에서 또는 /v1/api_keys/{workspaceId}/{id}에 DELETE를 보내 키를 폐기하세요. 키를 만든 사람이나 워크스페이스 관리자가 삭제할 수 있습니다.
스코프
스코프는 리소스와 동작을 짝지으며, 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_로 시작하는 클라이언트 ID와 한 번만 표시되는 클라이언트 시크릿이 반환됩니다. 시크릿을 잃어버리면 클라이언트 페이지에서 Rotate하세요. 이전 시크릿은 즉시 동작을 멈춥니다.
인가 흐름
Polylane은 PKCE(S256)를 사용하는 OAuth 2.0 인가 코드 흐름을 구현합니다.
사용자를 동의 페이지로 보내기
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을 POST하세요. 리프레시 토큰은 일회용입니다: 갱신할 때마다 대체 토큰이 반환됩니다.
모든 엔드포인트 URL을 포함한 서버 메타데이터는 https://api.polylane.com/v1/.well-known/oauth-authorization-server에 게시되며, 제공자는 /v1/oauth/userinfo와 /v1/oauth/introspect도 제공합니다. 애플리케이션이 보유한 토큰을 폐기하려면 토큰과 클라이언트 자격 증명을 담아 /v1/oauth/revoke에 POST를 보내고, token_type_hint를 access_token 또는 refresh_token으로 설정하거나 생략해 둘 다 시도하게 하세요. 클라이언트 페이지에서 클라이언트를 삭제하면 더 이상 인가를 시작하지 못합니다.
코딩 에이전트
코딩 에이전트를 연결하는 데 OAuth 클라이언트는 필요하지 않습니다. https://mcp.polylane.com/mcp의 호스팅된 MCP 서버는 동적 클라이언트 등록으로 자체 OAuth 흐름을 실행하며 API 키도 받습니다. 플랫폼 MCP 서버를 참고하세요.
관련 문서
- 클라이언트를 등록하지 않고 에디터 에이전트를 연결하려면 플랫폼 MCP 서버를 참고하세요.
- 브라우저, 디바이스 코드 또는 API 키로 CLI에 로그인하려면 CLI 인증을 참고하세요.
- 모든 엔드포인트와 필요한 스코프는 API 레퍼런스를 참고하세요.