APIトークン ガイド

概要

APIトークンは、KID連携サービス（FormOK 等）のAPIをプログラムから利用するための認証キーです。

KIDが発行・検証・管理を一元的に行うため、各サービス個別のAPI認証を設定する必要はありません。1つのトークンで対象サービスのAPIに安全にアクセスできます。

仕組み

APIトークンによる認証は、以下の流れで行われます。

あなたのアプリ                  連携サービス                KID
      |                           |                      |
      | --- APIリクエスト --------> |                      |
      |    (Bearer kid_xxxx...)    |                      |
      |                           | --- トークン検証 ----> |
      |                           |    (verify API)       |
      |                           | <-- 検証結果 --------- |
      |                           |    (有効/無効/スコープ)  |
      | <-- レスポンス ----------- |                      |
      |                           |                      |

トークンの作成と使い方

リクエスト例

以下のように Authorization ヘッダーと X-Api-Key ヘッダーを付与してAPIを呼び出します。

# curlでの例
curl -H "Authorization: Bearer kid_xxxxxxxxxxxx..." \
     -H "X-Api-Key: your_api_key_here" \
     https://example.com/api/endpoint

// JavaScriptでの例
const res = await fetch('https://example.com/api/endpoint', {
  headers: {
    'Authorization': 'Bearer kid_xxxxxxxxxxxx...',
    'X-Api-Key':      'your_api_key_here'
  }
});

# Pythonでの例
import requests

headers = {
    'Authorization': 'Bearer kid_xxxxxxxxxxxx...',
    'X-Api-Key':      'your_api_key_here',
}
res = requests.get('https://example.com/api/endpoint', headers=headers)

APIリファレンス

連携サービスのサーバーがKIDにトークンの有効性を問い合わせるためのAPIです。

トークン検証

トークンが有効かどうかを検証します。連携サービスのバックエンドから呼び出してください。

リクエストヘッダー

{
  "result_code":   0,
  "valid":         true,
  "token_id":      "a1b2c3d4e5f6g7h8",
  "account_id":    "xxxxxxxxxxxxxxxx",
  "scopes":        ["read", "write"],
  "custom_scopes": {"base_id": ["my-knowledge", "team-docs"]},
  "expires_at":    "2027-03-10T12:00:00+09:00",
  "remaining_ttl": 31536000
}

custom_scopes はアプリ固有のカスタムスコープ値です。APIオーナが定義し、ユーザーがトークン発行時に設定します。未設定の場合は {} が返ります。

アカウント情報取得

トークン所有者のKIDアカウント情報を取得します。read スコープが必要です。

リクエストヘッダー

{
  "result_code": 0,
  "account_id":  "xxxxxxxxxxxxxxxx",
  "email":       "user@example.com",
  "full_name":   "山田 太郎",
  "locale":      "ja_JP",
  "status":      "A"
}

スコープ

スコープはトークンの操作権限を定義します。必要最小限のスコープを選択してください。

カスタムスコープ

アプリのオーナーが独自のスコープを定義できます。例えば、アクセスを許可するリソースIDの制限などに利用します。

制限事項

発行上限

有効期限

レート制限

トークンごとにリクエスト数の上限を設定できます（1分あたり）。

セキュリティ

トークンの安全な取り扱い

• 秘密情報として扱う — トークンはパスワードと同等の機密情報です。ソースコードや公開リポジトリには含めないでください。
• 環境変数で管理 — トークンは環境変数や秘密管理サービス（AWS Secrets Manager 等）で管理してください。
• HTTPS通信のみ — トークンは必ずHTTPS経由で送信してください。HTTP通信では傍受されるリスクがあります。
• 必要最小限のスコープ — トークン作成時は、用途に必要な最小限のスコープだけを選択してください。
• 不要なトークンは失効 — 使わなくなったトークンは速やかに失効してください。

トークンの保存方式

KIDはトークンの生データを保持しません。サーバーにはSHA-512ハッシュのみが保存されるため、万が一データベースが漏洩してもトークンの悪用はできません。

3層レート制限

不正アクセスを多層的に防御しています。

• Layer 1 - nginx — IP単位でのDoS防御（秒間10リクエスト制限）
• Layer 2 - 不正検証ブロック — 無効なトークンを繰り返し送信するIPを自動ブロック
• Layer 3 - トークン単位 — トークンごとに設定されたレート制限を適用

トークン管理

管理画面

KIDにログイン後、以下の方法でトークン管理画面にアクセスできます。

• 連携サービスの「APIトークン管理」リンクからアクセス（推奨）
• 直接URLアクセス: /token/{api_key} で対象アプリのトークン管理
• /token で発行済みトークンの一覧を確認

変更可能な項目

ステータス

エラーコード

トークン検証時に返される主なエラーです。

{
  "result_code": 1,
  "error":       "token_expired"
}

FAQ

トークンを紛失しました。再表示できますか？

いいえ。セキュリティ上、トークンは作成時の1回のみ表示されます。紛失した場合は、既存トークンを失効して新しいトークンを発行してください。

トークンのスコープや有効期限を変更したい

スコープ・有効期限・対象アプリは作成後に変更できません。既存トークンを失効し、新しい設定で再発行してください。

トークンを一時的に停止したい

トークン管理画面の編集からステータスを「無効」に変更してください。無効化中はAPIリクエストが拒否されます。再び「有効」に戻すことも可能です。

「失効」と「無効」の違いは？

無効は一時的な停止で、再度有効に戻せます。失効は永久的な無効化で、元に戻すことはできません。

1つのトークンで複数のアプリを利用できますか？

いいえ。1つのトークンは1つのアプリに紐づきます。複数のアプリを利用する場合は、アプリごとにトークンを発行してください。

レート制限に達した場合はどうすれば？

しばらく待ってから再試行してください。レート制限は1分間のリクエスト数で計算されるため、1分後にはリセットされます。必要に応じてトークン管理画面からレート制限値を引き上げることもできます。

X-Api-Key は何のために必要ですか？

トークンが対象アプリ用に発行されたものかを確認するために必要です。これにより、あるアプリ用のトークンで別のアプリのAPIにアクセスすることを防ぎます。