API キー

概要

API キーは、ユーザー個人が発行する認証トークンです。CLI ツール、MCP サーバー、アドホックなスクリプトなど、個人の API アクセスに使います。

App の Client Credentials（app_credential）がアプリケーション単位のアクセスであるのに対し、API キーはユーザー個人に紐づくアクセス手段です。

API キーの発行

1. id.speria.jp にログイン
2. マイページの「API キー」セクションを開く
3. 「API キーを作成」から以下を設定:
   • 名前 — キーの用途を識別する表示名
   • Workspace — アクセスを許可する Workspace を選択
   • スコープ — アクセスを許可するリソースの範囲を選択

発行されたキーは 一度だけ表示 されます。紛失した場合は再発行してください。

権限モデル

API キーの実効権限は、ユーザーの権限 と トークンの制限 の交差で決まります。

実効権限 = ユーザーの Membership 権限 ∩ API キーの制限（Workspace + スコープ）

• API キーに Workspace を指定しても、その Workspace の Membership がなければアクセスできません
• Membership が外れた場合、API キーの設定に関わらずその Workspace へのアクセスは無効になります
• スコープは発行時に指定したもののみ有効です。後から追加されたスコープは自動で付与されません

API リクエスト

Authorization ヘッダーに API キーを設定してリクエストします。

GET https://api.speria.jp/v1/workspaces/{workspace_id}/customer_visits
Authorization: Bearer speria_key_xxxxxxxx

API エンドポイントの仕様は API リファレンス を参照してください。

トークン仕様

ベストプラクティス

最小権限の原則

• Workspace は必要なものだけを指定する
• スコープは用途に必要な最小限を選択する

キーの管理

• 用途ごとにキーを分けて発行し、名前で識別できるようにする
• 使わなくなったキーは速やかに失効させる
• キーをコードにハードコードしない。環境変数やシークレット管理サービスを利用する
• 漏洩の疑いがある場合はただちに失効させ、新しいキーを発行する