学べること
- 3つのAPIキーロール（viewer、editor、admin）と、それぞれがアクセスできるエンドポイント。
- ダッシュボード、CI/CDパイプライン、管理者自動化、AIエージェントなど、よくあるユースケースに適したロール。
- 403エラーレスポンスを読み取り、連携に必要なロールを正確に特定する方法。
すべての Elido APIキーにはロールが割り当てられています。ロールによって、そのキーで実行できる操作が決まります。ユースケースごとに必要最小限の権限を持つロールを選択することで、万が一キーが漏洩した場合の影響範囲を最小限に抑えることができます。
3つのロール#
| ロール | 実行可能な操作 |
|---|---|
| viewer | リンク、アナリティクス、ワークスペース設定の閲覧。作成、更新、削除は一切行えません。 |
| editor | viewerができるすべての操作に加え、リンクの作成/更新/削除、ウェブフックの管理、一括インポートの実行。 |
| admin | editorができるすべての操作に加え、ワークスペースメンバー、請求、APIキー、およびIPルールの管理。 |
ロールは、Settings → API keys でキーを作成する際に設定します。作成後にキーのロールを変更することはできません。適切なロールを持つ新しいキーを発行し、古いキーを無効化してください。
どのロールを使用すべきか#
アナリティクスダッシュボードおよび読み取り専用の連携 — viewer を使用してください。サードパーティのBIツール、クリック数を取得するステータスページ、または内部レポート用のスクリプトなどは、データの読み取りのみを必要とします。
リンクを短縮するCI/CDパイプライン — editor を使用してください。キャンペーンリンクを作成するデプロイスクリプト、短縮URLを生成するCMS連携、およびほとんどの Zapier/Make の自動化がこれに該当します。
管理者用自動化 — 連携においてメンバー管理や請求管理が真に必要な場合にのみ admin を使用してください。これは一般的ではありません。「管理者向け」に感じられる連携の多くは、実際には editor で十分です。
MCP server / AI エージェント — エージェントがメンバーを招待する必要がない限り、editor が適切なデフォルトです。@elido/mcp-server パッケージはキーのロールに従います。
ロールとエンドポイントの対応#
一般的な API コールのクイックリファレンス：
GET /v1/links → viewer
POST /v1/links → editor
PUT /v1/links/:id → editor
DELETE /v1/links/:id → editor
GET /v1/analytics/clicks → viewer
GET /v1/workspace → viewer
POST /v1/workspace/members → admin
POST /v1/api-keys → admin
詳細なリファレンスは /api で確認できます。
スコープ不一致エラー#
キーがエンドポイントに対する権限を持っていない場合、API は以下を返します。
{
"error": "forbidden",
"message": "this key requires the admin role to manage workspace members",
"required_role": "admin",
"key_role": "editor"
}
required_role フィールドには、必要なロールが示されます。修正するには、より上位のロールを持つ新しいキーを発行するか（それが意図的である場合）、その連携でその操作を実行する必要があるかどうかを再検討してください。
よくある間違い：
viewerキーを使用してリンクを作成しようとする。解決策：editorキーを発行してください。- スクリプトからチームメンバーを招待するために
editorキーを使用する。解決策：adminキーを発行するか、代わりにダッシュボードを使用してください。 - ワークスペースレベルのメンバーシップロール（オーナー/メンバー）と APIキーのロールを混同する。これらは別の概念です。「メンバー」権限を持つチームメンバーであっても、自身の連携のために
adminロールの APIキーを作成できます。ダッシュボードの権限がキーに引き継がれるわけではありません。
トラブルシューティング#
許可されるべきエンドポイントで403エラーが発生する場合。 Settings → API keys でキーのロールを再確認してください。ロール列に表示されています。ロールが正しい場合は、Basic認証ヘッダーやクエリパラメータではなく、Authorization: Bearer <token> ヘッダーを送信していることを確認してください。
401 Unauthorized。 キーが無効化されているか、トークンが間違っています。Status列に revoked バッジが表示されていないか確認してください。キーが有効な場合は、作成時にトークンを完全にコピーしたか確認してください。
読み取りはできるが書き込みに失敗する場合。 お使いのキーはおそらく viewer です。新しい editor キーを発行してください。
連携ごとに異なる権限が必要な場合。 連携ごとに1つのキーを発行してください。キーの作成は無料で、個別に無効化するのも簡単です。そのため、2つのシステム間でキーを共有する必要はありません。