API認証

Showly REST API は 2 つの認証情報タイプを受け入れます。ユースケースに合ったものを選択してください。ベース 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_) を使用します。彼らは：

• 発行ユーザーであるあなたとして監査ログを記録します (説明責任のために役立ちます)。
• 1 つのワークスペースにバインドされています。自動化するワークスペースごとに 1 つ作成します。
• 同じ 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 を分岐条件にしないでください。スコープ名は site:read や preview:create のような正式な resource:verb 形式です。完全な一覧はスコープとトークンを参照してください。

grant_type=refresh_token エンドポイントはありません。 MCP トークンを更新するには、POST /admin/mcp-tokens/:tokenId/rotate をローテーションします。

賢明な選択