REST API の認証と API トークン
この機能は Ver. 3.3.0 で追加予定の、リリース前の機能です
このページは、アルファ版(Ver. 3.3.0-alpha.1)時点の内容です。正式版までに仕様や設定項目が変わる可能性があります。本番サイトでは使わず、検証環境でお試しください。
REST API は、ユーザーごとに発行する API トークン(アプリパスワード方式の Bearer トークン)で認証します。トークンは、発行したユーザーの代わりに操作するための合言葉です。このページでは、発行・失効の手順と、スコープ(トークンでできる操作の範囲)、管理画面の権限との関係を説明します。
API トークンを発行する
トークンは、API を使うユーザーが自分で発行します。管理者がほかのユーザーのトークンを発行することはできません。
API を使うユーザーで管理画面にログインし、プロフィール変更のユーザー編集画面の「API トークン」で「管理する」を開きます。
「トークンを発行」で、トークン名(必須。用途が分かる名前。例:
記事の連携用)、スコープ(必要なものだけ。初期値はread。選び方は下の「スコープの選び方」)、有効期限(30 日・90 日・1 年・無期限・日付指定。初期値は 90 日。サイトに有効期限の上限(既定 365 日)があるときは、上限を超える選択肢と「無期限」は選べません)を指定して発行します。発行直後に表示されたトークンを控えます。閉じた後は二度と表示できません。
トークンは
acms_に 64 桁の 16 進数が続く文字列です。サーバーにはハッシュだけを保存するため、あとから確かめる方法はありません。控え忘れたら失効して発行し直します。1 ユーザーが発行できるトークンは 20 個までです(期限切れのトークンも数えます)。上限に達すると「発行できる API トークンの数の上限(20 個)に達しています。」と表示されます。
トークンを発行できるのは、「REST API設定」の「API・MCP を使える権限」で許可された権限種別のユーザー(ロールを使う場合は、ロールの「API・MCP の接続」が有効なユーザー)だけです。許可されていないと「API・MCP を使う権限がないため、API トークンを発行できません。」と表示されます。
発行すると、本人にメールで知らせます(「メール設定」の「API の接続の通知」。REST API を有効にする)。覚えのない知らせが届いたら、すぐに失効してください。
トークンは秘密の値として扱ってください
トークンは、発行したユーザーと同じ権限で操作できます。ソースコード・設定ファイル・ログ・チケットに書かず、環境変数やシークレットの管理機能に置いてください。漏れた疑いがあるときは、すぐに失効して発行し直してください。
トークンを使う
トークンは Authorization ヘッダーに Bearer を付けて送ります。クエリ文字列や Cookie では送れません。
curl -H "Authorization: Bearer ${ACMS_API_TOKEN}" https://example.com/rest-api/acms/v1/me/トークンで操作できるブログは、トークンの持ち主の所属ブログと、その子孫のブログです。子孫のブログを操作できるのは、ユーザーの「子ブログへの権限」で「子ブログにも権限を与える」が有効な場合だけです(REST API の global_auth)。それ以外のブログの URL で呼ぶと 403 blog_not_allowed になります。
トークンを失効する
本人が失効する手順です。
ユーザー編集画面の「API トークン」で、失効するトークンを選んで失効します。失効したトークンは元に戻せません。
ルートブログの管理者は、管理画面の「API 連携」で、すべてのユーザーのトークンを確かめて失効できます。トークンごとの実行ログ(監査ログ)への入口もあります。
次の場合も、トークンは使えなくなります。
有効期限が切れたとき(401
token_expired)ユーザーを無効にしたとき(401
user_disabled)「API・MCP を使える権限」(ロールの「API・MCP の接続」)の許可を外したとき(403
api_access_not_allowed。許可を戻せば、また使えます)バックアップをリストアしたとき(リストアの後に、トークンを発行し直してください)
スコープの一覧
スコープは、トークンでできる操作の範囲です。発行時に、「まとめて選ぶ」(read / write)、「リソースごとに選ぶ」、「強い権限」から選びます。広いスコープは狭いスコープを含みます。「満たすスコープ」の列は、そのスコープを持つトークンが、どのスコープの要るエンドポイントを呼べるかを示します。
まとめて選ぶ
スコープ | 許す操作 | 満たすスコープ |
|---|---|---|
| 強い権限を除く、すべてのリソースの読み取り |
|
| 強い権限を除く、すべてのリソースの読み書き。 |
|
リソースごとに選ぶ
{リソース}:write は、同じリソースの {リソース}:read を含みます。
スコープ | 許す操作(エンドポイント) | 含まれるまとめたスコープ |
|---|---|---|
|
|
|
| エントリーの作成・更新・削除・ゴミ箱から戻す・複製、編集ロック、共有プレビュー、バージョンの作成・上書き・削除・複製(公開中のエントリーを変える操作を除く) |
|
| メディアの取得 / アップロード・取り込み・差し替え・更新・削除 |
|
| カテゴリーの取得 / 作成・更新・削除 | 同上 |
| ブログの取得 / 子ブログの作成・URL のブログの更新・削除 | 同上 |
| モジュール ID の取得 / 作成・更新・複製・削除 | 同上 |
|
| 同上 |
| ルールの取得 / 作成・更新・削除 | 同上 |
| コンフィグセットの取得 / 作成・更新・削除 | 同上 |
| ブログ・ルール・コンフィグセットの設定キーの取得 |
|
| フィールドセット・フィールド定義の取得 |
|
| (読み取りのコアのエンドポイントはありません)/ |
|
| (読み取りのコアのエンドポイントはありません)/ | 同上 |
強い権限(専用スコープ)
個人情報や管理者向けの情報を読む操作と、サイト全体に影響する操作は「強い権限」です。read / write には含まれず、そのスコープ自身を選んだトークンだけが使えます({リソース}:write は同じリソースの {リソース}:read を含みます)。
スコープ | 許す操作 |
|---|---|
| エントリーの公開・非公開・バージョンの公開・承認フローの最終承認と、公開中のエントリーの作成・更新・削除(下の「entries:publish の範囲」) |
| 設定キーの更新( |
| フィールドセット・フィールド定義の作成・更新・削除・キーの変更。 |
| ユーザーの取得 / 作成・更新・削除 |
| エイリアスの取得 / 作成・更新・削除 |
| フォーム ID と投稿ログの取得 / フォーム ID の作成・更新・複製・削除 |
| ユーザーグループの取得 / 作成・更新・削除 |
| ロールの取得 / 作成・更新・削除 |
| Webhook の取得 / 作成・更新・削除・テスト送信 |
| リダイレクトの取得 / 作成・更新・削除・並べ替え |
| 監査ログの取得 |
| 承認フローの操作( |
| データベースのバックアップのジョブ |
| エントリーの CSV インポートのジョブ |
| WordPress(WXR)形式のエクスポートのジョブ |
| 静的書き出しのジョブ |
| プラグインの有効化・無効化のジョブ |
プラグインが追加したスコープも、発行画面に並びます(プラグインから REST API を拡張する)。各エンドポイントに要るスコープは REST API のエンドポイント一覧 を参照してください。
entries:publish の範囲
公開中のエントリーを変える操作には、entries:write とは別に entries:publish が要ります。write や entries:write だけのトークンでは公開できません。必要になるのは次の操作です。
POST /entries/{id}/publish・POST /entries/{id}/unpublish・POST /entries/{id}/revisions/{revisionId}/publish公開(
status: open)でのエントリーの作成(承認フローを経て承認前になる作成は除く)変える前か後が公開中のエントリーの更新(
PATCH/PUT /entries/{id}、作業領域の上書きでメインも更新する場合)公開中のエントリーの削除(ゴミ箱へ移すことを含む)
承認フローの最終承認(
POST /entries/{id}/approvalsのaction: publish)
公開中のエントリーを新しいバージョンとして保存する操作(POST /entries/{id}/revisions)と、下書き・非公開での作成・更新は、entries:write だけでできます。外部のツールや AI には entries:publish を渡さず、公開は人が管理画面で行う、という分担ができます。
スコープの選び方
用途 | 選ぶスコープ |
|---|---|
サイトのデータを読むだけ(集計・バックアップの確認・静的サイトの生成など) |
|
外部のシステムから記事を下書きで入稿し、公開は人が行う |
|
外部のシステムから記事を公開まで自動で行う |
|
サイトの構成(カテゴリー・モジュール ID・ルール)も含めて作る |
|
リダイレクトを一括で登録する |
|
監査ログを外部のログ基盤へ取り込む |
|
夜間にバックアップを取る |
|
管理画面の権限との関係
操作が許されるのは、トークンのスコープと、管理画面と同じ権限の判定(ブログ・カテゴリー・ロールによる権限、承認フロー、編集ロック)の両方を満たしたときだけです。スコープで権限が広がることはありません。
足りないもの | ステータス |
|
|---|---|---|
トークンのスコープ | 403 |
|
管理画面の権限 | 403 |
|
閲覧の権限(非公開のエントリー・権限の無いブログのカテゴリーなど) | 404 |
|
閲覧する権限の無いリソースは、存在しないものと同じく 404 を返します。存在を知らせないためです。
組み合わせの例
ユーザーの権限 | トークンのスコープ | できること | できないこと(応答) |
|---|---|---|---|
編集者 |
| 下書き・非公開のエントリーの作成。ブログのエントリー(ほかのユーザーのものを含む)のうち、公開中でないものの更新とゴミ箱への移動。公開中のエントリーの新しいバージョンの作成( | 公開・非公開の切り替え、公開での作成、公開中のエントリーの更新・削除(403 |
編集者 |
| 上の行のすべてと、公開・非公開、公開中のエントリーの更新・削除、メディア・カテゴリー・タグの操作 | モジュール ID・ルール・コンフィグセットなど、管理画面で管理者だけができる操作(403 |
投稿者 |
| 自分のエントリーの作成・更新・公開・削除(管理画面の投稿者と同じ範囲) | ほかのユーザーのエントリーの更新(403 |
管理者 |
| 強い権限を除く、すべてのリソースの読み取り | 書き込みすべて(403 |
読者(既定の設定) | — | — | トークンを発行できません。「API・MCP を使える権限」で読者を許可しても、操作は管理画面の読者の権限の範囲に限られます |
スコープが足りないときは、WWW-Authenticate ヘッダーの scope に、要るスコープが入ります。プログラムからは、このヘッダーで足りないスコープを知らせられます。
curl -i -X PATCH "${ACMS_API}/entries/240/" -H "Authorization: Bearer ${ACMS_API_TOKEN}" \
-H "Content-Type: application/json" -d '{"title":"x"}'HTTP/2 403
content-type: application/problem+json; charset=utf-8
www-authenticate: Bearer realm="a-blog cms", error="insufficient_scope", scope="entries:write"
{"type":"https://developer.a-blogcms.jp/rest-api/problems/insufficient-scope","title":"トークンのスコープが不足しています。","status":403,"instance":"/rest-api/acms/v1/entries/240/","code":"insufficient_scope"}OAuth 認可サーバーを有効にしているサイトでは、WWW-Authenticate に resource_metadata などの OAuth 用の値も付きます。REST API のトークンで使うときは無視してかまいません。
認証に失敗したとき
ステータス |
| 場面 |
|---|---|---|
401 |
| トークンが送られていない(ヘッダーが Web サーバーで落とされている場合を含む) |
401 |
| トークンが正しくない・失効している |
401 |
| トークンの有効期限が切れている |
401 |
| トークンの持ち主のユーザーが利用できない |
403 |
| トークンの持ち主が操作できないブログの URL で呼んだ |
403 |
| このユーザーに API・MCP の利用が許可されていない |
401 には WWW-Authenticate: Bearer realm="a-blog cms" が付きます(invalid_token などでは error="invalid_token" も付きます)。失敗の詳しい理由はレスポンスに出さず、監査ログに残します。同じ接続元の IP アドレスから認証の失敗が 1 分あたり 10 回(rest_api_auth_failure_limit_per_minute)に達すると、その接続元には 10 分間、トークンを照合せずに 429 rate_limited と Retry-After を返します。
よくある質問・つまずき
「API トークン」の行がユーザーの編集画面に出ません
「API トークン」の行は、自分自身のユーザーの編集画面にだけ出ます。ほかのユーザーの編集画面には出ません。そのユーザーにログインしてもらい、本人が発行します。
スコープを選び直したい
発行済みのトークンのスコープは変えられません。新しいスコープでトークンを発行し、古いトークンを失効してください。
write を付けたのにユーザーや監査ログが読めません
ユーザー・監査ログなどは「強い権限」で、write に含まれません。users:read・audit-logs:read などを個別に選んだトークンを発行してください。
管理者なのに 403 forbidden になります
URL のブログで権限があるかを確かめます。子ブログの URL で呼んでいる場合、ユーザーの「子ブログへの権限」が無いと 403 blog_not_allowed、ロールを使っている場合はロールの管轄ブログ・権限によって forbidden になります。GET /me の auth と blog_id で、そのブログでの判定を確かめられます。