Skip to Content
APIリファレンス認証

認証

TWP公開APIの認証方法について説明します。

APIキー認証

TWP公開APIは、APIキーによる認証を使用します。すべてのAPIリクエストには有効なAPIキーが必要です。

APIキーの取得

  1. TWP管理画面にログイン
  2. 「組織管理」→「APIキー」を開く
  3. 「新規作成」をクリック
  4. 名前・説明・パーミッション・有効期限（任意）を設定して作成

作成したキーは twpk_ で始まります（組織APIキー）。個人用APIキー（twpu_）はMCP連携用で、公開APIのコンテンツ・問い合わせには使えません。

権限設定

APIキー作成時に、以下の権限を設定できます。

権限説明
cms:readコンテンツ・カテゴリの取得（GET /v1/cms/*）
cms:searchコンテンツ検索（POST /v1/cms/search）
cms:*コンテンツAPIの全機能（上記2つを含む）
inquiry:create問い合わせの作成

必要な権限のみを付与することを推奨します。付与していない権限のエンドポイントを 呼び出すと 403 FORBIDDEN（Insufficient permissions）になります。 コンテンツの取得と検索は別の権限なので、検索も使う場合は cms:search（または cms:*）も付与してください。

APIリクエストの認証

APIキーを X-API-Key ヘッダーに含めてリクエストします。

X-API-Key: your_api_key_here

リクエスト例

curl -X GET "https://api.tocca.systems/v1/cms/contents" \
  -H "X-API-Key: your_api_key_here" \
  -H "Content-Type: application/json"

JavaScript (fetch) の例

const response = await fetch(
  'https://api.tocca.systems/v1/cms/contents?category_code=news',
  {
    headers: {
      'X-API-Key': 'your_api_key_here',
      'Content-Type': 'application/json',
    },
  }
);
 
const data = await response.json();

プレビュートークン（コンテンツAPI用）

コンテンツAPIでは、未公開コンテンツをプレビューするためのトークンを使用できます。

プレビュートークンの取得

TWP管理画面のコンテンツ編集画面から「プレビュー」ボタンでプレビューURLを生成できます。URLに含まれるトークンをAPIで使用できます。

使用方法

X-Preview-Token: preview_token_here

または、クエリパラメータで指定：

?preview_token=preview_token_here

ブラウザから直接呼び出す場合は、クエリパラメータ（preview_token）を使ってください。X-Preview-Token ヘッダーはCORSの許可ヘッダーに含まれていないため、ブラウザのプリフライトで拒否されます。

注意事項

  • プレビュートークンには有効期限があります
  • トークンは特定のコンテンツまたはカテゴリに紐づいています
  • 本番環境では公開済みコンテンツのみ使用してください

セキュリティ上の注意

APIキーの保護

  • APIキーはサーバーサイドで使用してください
  • クライアントサイド（ブラウザのJavaScript）にAPIキーを埋め込まないでください
  • バージョン管理システムにAPIキーをコミットしないでください

推奨構成

[ユーザーブラウザ] → [自社サーバー] → [TWP API]
                       ↑
                  APIキーはここで管理

APIキーの定期的なローテーション

セキュリティ強化のため、APIキーを定期的に再生成することを推奨します。

  1. 新しいAPIキーを作成
  2. アプリケーションを新しいキーに更新
  3. 古いキーを削除

HTTPS必須

すべてのAPIリクエストはHTTPS経由で行ってください。HTTP接続は受け付けません。

APIキーの無効化・削除

不要になったAPIキーや、漏洩の疑いがあるAPIキーは速やかに無効化または削除してください。

  1. TWP管理画面の「組織管理」→「APIキー」を開く
  2. 該当キーの行のメニューから「無効にする」（または削除）を選ぶ

無効化・削除したキー、有効期限が切れたキーでのリクエストには、403 と {"message": "Forbidden"} が返ります。無効化したキーは同じメニューの「有効にする」で元に戻せます。無効化・削除が反映されるまで、最大1分程度かかることがあります。

Last updated on
概要コンテンツAPI