権限を作成

POST /v1/permissions · 権限 apis:write

API に権限（OAuth スコープ）を追加します。同意画面に表示するテキストも必要に応じて指定できます。Idempotency-Key に対応しています。

リクエスト

フィールド 型 必須 説明
api_id string はい 対象の API（api_…）。
value string はい スコープの値。resource:action 形式（^[a-z0-9_.-]{1,64}:[a-z0-9_.*-]{1,64}$）。API 内で一意であり、変更できません。idp_ プレフィックスは予約されています。
display_name string | null いいえ 同意画面で、スコープの値の代わりに表示される短い名前。128 文字以内。
description string | null いいえ 同意画面で名前の下に表示される詳細説明。1024 文字以内。
consent_text_i18n object | null いいえ 言語タグから同意画面のテキストへの対応。例：{"en": "Read your orders"}。30 言語まで、各テキストは 1〜1024 文字、合計 16 KiB まで。
sensitivity string いいえ normal（既定）または sensitive。

同意画面のテキスト

提供される同意画面では、要求された各スコープを次のように表示します。ページの言語に対応する consent_text_i18n の項目（タグが完全一致するもの、なければその基本サブタグ）を使い、それもなければ display_name、さらになければスコープの value を使います。description は詳細行として表示されます。3 つはいずれもプレーンテキストです。制御文字（改行やタブを含む）、行区切りと段落区切り、双方向の埋め込み、オーバーライド、分離の文字（U+202A-U+202E、U+2066-U+2069）は 422 で拒否されます。前後の空白は取り除かれ、トリミング後に空になるテキストは null として保存されます。HTML は解釈されず、同意画面ではエスケープされて表示されます。

レスポンス

201 Created

{
  "id": "perm_01h455vb4pex5vsknk084sn02s",
  "api_id": "api_01h455vb4pex5vsknk084sn02q",
  "value": "read:orders",
  "display_name": "Read orders",
  "description": "See your past orders and their status",
  "consent_text_i18n": {
    "en": "Read your orders",
    "tr": "Siparişlerinizi okuyun"
  },
  "sensitivity": "normal"
}

エラー

HTTP code 発生条件
400 unknown_field リクエストボディに未知のフィールドが含まれています。
403 insufficient_permissions 認証情報に apis:write がありません。
403 quota_exceeded API にすでに 1,000 件の権限があります。
404 not_found この環境に該当する API が存在しません。
409 conflict 同じ value がこの API にすでに存在するか、対象がシステム API です。
422 validation_failed フィールドが欠けているか無効であるか、テキストがプレーンテキストではありません（errors[].pointer が該当フィールドを示します。例：/consent_text_i18n）。

例

curl -X POST https://api.eu.keenauth.com/v1/permissions \
  -H "Authorization: Bearer $KEENAUTH_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 6f1d2c1e-perm-create" \
  -d '{"api_id":"api_01h455vb4pex5vsknk084sn02q","value":"read:orders","display_name":"Read orders","consent_text_i18n":{"en":"Read your orders"}}'

CLI を使う場合は、--data で言語マップを渡します。

echo '{"consent_text_i18n":{"en":"Read your orders"}}' | keenauth permissions create \
  --api-id api_01h455vb4pex5vsknk084sn02q --value read:orders --display-name "Read orders" --data -