API のトークンと権限

APIを使うには、鍵が必要です。鍵には、できること（権限）と触れるデータを決められます。この記事では、鍵の種類と、安全な決めかたを説明します。

鍵は2種類

種類	使いどころ	権限の決まりかた
個人アクセストークン	自分用のスクリプト、動作の確認	持ち主の役割と同じ見え方。その上で、トークンに渡した権限の範囲に絞られる
APIクライアント	システムどうしの連携	鍵に付けた権限（スコープ）だけで決まる。人には結び付かない

どちらも、設計モードの「管理」›「連携と外部データ」›「連携（Webhook・API）」で作ります。「個人トークン」「APIクライアント」のタブから、鍵を足します。鍵を作るには、連携の鍵を管理する権限（apikey.manage）が必要です。

鍵を使う

APIを呼ぶときは、ヘッダーに鍵を付けます。

Authorization: Bearer （鍵）

使いかたは、REST APIで説明しています。

権限（スコープ）

権限は、役割の「できること」と同じ考えかたです。APIクライアントも、同じ権限の決まりに従います。APIだけが何でもできる抜け道はありません。

権限	できること
data.view	レコードを読む
data.create	レコードを登録する
data.update	レコードを更新する
data.delete	レコードを削除する
data.export	データを書き出す
form.view	フォームの定義を読む
report.output	帳票を出力する

連携に必要な権限だけを付けてください。読むだけの連携なら、data.viewだけで足ります。

触れるデータ・IP・上限

APIクライアントには、次の制限も付けられます。

• 触れるデータ: 使ってよいアプリを選ぶ。選んだ外のアプリには、403になります
• 許可するIP: 接続してよいIPアドレスを決める
• 1分の上限: 1分に呼べる回数（既定は600回）

APIクライアントの「見える行の範囲」は、意味があるのは「すべて」だけです。人やグループに結び付かないからです。「自分のもの」や「グループ」の設定は、何も見えない側に倒れます。グループの範囲で連携したいときは、その範囲の人の個人アクセストークンを使います。

個人情報の扱い

機密の項目は、APIでも、既定では伏せ字で返ります。実際の値を読めるのは、伏せ字を外す権限（data.view_masked）を付けた鍵だけです。この権限は、既定では付きません。

更新（PATCHなど）で、伏せ字や見えない項目を送っても、元の値は上書きされません。読んだ内容をそのまま書き戻す連携が、実際の値を伏せ字で壊さないための決まりです。

作ったあとに直す

APIクライアントの行を押すと、権限、触れるデータ、許可するIP、1分の上限を確かめられます。「権限などを直す」で、あとから変えられます。

直しかた	扱い
減らす（権限を外す、データやIPを絞る）	すぐ効く
増やす（権限を足す、絞りを外す）	保存の前に、増えるものを並べた確認の窓が出る。承知すると保存される

クライアントシークレットは変わりません。直した内容は、監査ログに、誰が何を増やした・減らしたかが残ります。

安全に使うために

• 鍵は、用途ごとに作り分ける（連携先ごとに1つ）
• 必要な権限と、触れるデータだけに絞る
• 使わなくなった鍵は、失効させる
• 鍵をメールやチャットに貼らない

関連する記事

• REST API
• Webhookで通知する
• 役割（ロール）を決める
• 監査ログ