API 인증

Showly REST API는 두 가지 자격 증명 유형을 허용합니다. 귀하의 사용 사례에 맞는 것을 선택하십시오. 기본 URL은 https://api.showly.ai입니다. 버전 접두사와 Api-Version 헤더가 없습니다.

개인 액세스 토큰(PAT)

대상: 임시 스크립트, 개인 자동화.

프로필 → API 토큰 → 새 토큰에서 발행합니다. PAT는 생성된 단일 작업 영역으로 범위가 지정되며 생성 시 부여한 범위를 전달합니다. 자격 증명으로 취급하십시오.

GET /sites HTTP/1.1
Host: api.showly.ai
Authorization: Bearer sk_live_...

PAT는 sk_live_ 접두사(또는 샌드박스의 경우 sk_test_)를 사용합니다. 그들:

• 발급 사용자로서 감사 로그를 작성합니다(책임에 좋습니다).
• 하나의 작업공간에 바인딩되어 있습니다. 자동화하는 작업공간당 하나씩 생성하세요.
• 동일한 UI에서 취소 및 순환됩니다. CI의 경우 각 파이프라인에 자체 PAT를 제공하고 일정에 따라 순환합니다.

MCP 토큰(장치 흐름)

대상: 사용자를 대신하여 행동하는 상담원 및 MCP 클라이언트(Claude Code, Codex).

에이전트 클라이언트는 RFC 8628 장치 인증 흐름을 통해 얻은 MCP 토큰으로 인증합니다. 토큰은 권한을 부여하는 사용자에게 바인딩되어 있으며 사용자가 동의한 범위를 전달합니다. MCP 토큰은 mcp_live_ 접두사(또는 샌드박스의 경우 mcp_test_)를 사용합니다.

장치 코드를 요청하여 흐름을 시작합니다.

POST /oauth/device
Content-Type: application/x-www-form-urlencoded

client_id=<your-app>
&scope=site:read preview:create

사용자는 브라우저에서 요청을 승인합니다(장치 흐름 조회/엔드포인트 승인이 확인 페이지로 돌아옴). 그 사이에 사용자가 승인을 완료할 때까지 장치 코드로 토큰 엔드포인트를 폴링합니다.

POST /oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=urn:ietf:params:oauth:grant-type:device_code
&device_code=<device-code>
&client_id=<your-app>

성공하면 MCP 토큰이 발행됩니다. 참고: POST /oauth/token는 원시 RFC 6749/8628 본문({ "access_token", "token_type": "Bearer", "scope" })을 반환합니다. 표준 { ok, data } 봉투를 사용하지 않기므로 거기에서 ok로 분기하지 마세요. 범위는 표준 resource:verb 어휘(예: site:read, preview:create)를 사용합니다. 전체 카탈로그는 범위 및 토큰을 참조하여 REST 및 MCP가 동기화되도록 하세요.

grant_type=refresh_token 엔드포인트가 없습니다. MCP 토큰을 갱신하려면 POST /admin/mcp-tokens/:tokenId/rotate 토큰을 교체하세요.

현명한 선택