REST API の認証と API トークン


この機能は Ver. 3.3.0 で追加予定の、リリース前の機能です

このページは、アルファ版(Ver. 3.3.0-alpha.1)時点の内容です。正式版までに仕様や設定項目が変わる可能性があります。本番サイトでは使わず、検証環境でお試しください。

REST API は、ユーザーごとに発行する API トークン(アプリパスワード方式の Bearer トークン)で認証します。トークンは、発行したユーザーの代わりに操作するための合言葉です。このページでは、発行・失効の手順と、スコープ(トークンでできる操作の範囲)、管理画面の権限との関係を説明します。

API トークンを発行する

トークンは、API を使うユーザーが自分で発行します。管理者がほかのユーザーのトークンを発行することはできません。

  1. API を使うユーザーで管理画面にログインし、プロフィール変更のユーザー編集画面の「API トークン」で「管理する」を開きます。

  2. 「トークンを発行」で、トークン名(必須。用途が分かる名前。例: 記事の連携用)、スコープ(必要なものだけ。初期値は read。選び方は下の「スコープの選び方」)、有効期限(30 日・90 日・1 年・無期限・日付指定。初期値は 90 日。サイトに有効期限の上限(既定 365 日)があるときは、上限を超える選択肢と「無期限」は選べません)を指定して発行します。

  3. 発行直後に表示されたトークンを控えます。閉じた後は二度と表示できません。

  • トークンは 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)、「リソースごとに選ぶ」、「強い権限」から選びます。広いスコープは狭いスコープを含みます。「満たすスコープ」の列は、そのスコープを持つトークンが、どのスコープの要るエンドポイントを呼べるかを示します。

まとめて選ぶ

スコープ

許す操作

満たすスコープ

read

強い権限を除く、すべてのリソースの読み取り

entries:read・media:read・categories:read・blogs:read・modules:read・tags:read・rules:read・config-sets:read・configs:read・field-definitions:read・cache:read・fulltext:read

write

強い権限を除く、すべてのリソースの読み書き。read を含みます

read が満たすものすべてと、entries:write・media:write・categories:write・blogs:write・modules:write・tags:write・rules:write・config-sets:write・cache:write・fulltext:write

リソースごとに選ぶ

{リソース}:write は、同じリソースの {リソース}:read を含みます。

スコープ

許す操作(エンドポイント)

含まれるまとめたスコープ

entries:read

GET /entries・GET /entries/{id}・GET /entries/editor-settings・GET /entries/{id}/lock・GET /entries/{id}/revisions・GET /entries/{id}/revisions/{revisionId}・GET /entries/{id}/approvals

read・write

entries:write

エントリーの作成・更新・削除・ゴミ箱から戻す・複製、編集ロック、共有プレビュー、バージョンの作成・上書き・削除・複製(公開中のエントリーを変える操作を除く)

write

media:read / media:write

メディアの取得 / アップロード・取り込み・差し替え・更新・削除

read・write / write

categories:read / categories:write

カテゴリーの取得 / 作成・更新・削除

同上

blogs:read / blogs:write

ブログの取得 / 子ブログの作成・URL のブログの更新・削除

同上

modules:read / modules:write

モジュール ID の取得 / 作成・更新・複製・削除

同上

tags:read / tags:write

GET /tags / GET /tags/{name}(管理用の取得)・名前の変更・削除

同上

rules:read / rules:write

ルールの取得 / 作成・更新・削除

同上

config-sets:read / config-sets:write

コンフィグセットの取得 / 作成・更新・削除

同上

configs:read

ブログ・ルール・コンフィグセットの設定キーの取得

read・write

field-definitions:read

フィールドセット・フィールド定義の取得

read・write

cache:read / cache:write

(読み取りのコアのエンドポイントはありません)/ POST /cache/clear

read・write / write

fulltext:read / fulltext:write

(読み取りのコアのエンドポイントはありません)/ POST /fulltext/rebuild

同上

強い権限(専用スコープ)

個人情報や管理者向けの情報を読む操作と、サイト全体に影響する操作は「強い権限」です。read / write には含まれず、そのスコープ自身を選んだトークンだけが使えます({リソース}:write は同じリソースの {リソース}:read を含みます)。

スコープ

許す操作

entries:publish

エントリーの公開・非公開・バージョンの公開・承認フローの最終承認と、公開中のエントリーの作成・更新・削除(下の「entries:publish の範囲」)

configs:write

設定キーの更新(PATCH /configs など)。configs:read を含みます

field-definitions:write

フィールドセット・フィールド定義の作成・更新・削除・キーの変更。field-definitions:read を含みます

users:read / users:write

ユーザーの取得 / 作成・更新・削除

aliases:read / aliases:write

エイリアスの取得 / 作成・更新・削除

forms:read / forms:write

フォーム ID と投稿ログの取得 / フォーム ID の作成・更新・複製・削除

usergroups:read / usergroups:write

ユーザーグループの取得 / 作成・更新・削除

roles:read / roles:write

ロールの取得 / 作成・更新・削除

webhooks:read / webhooks:write

Webhook の取得 / 作成・更新・削除・テスト送信

redirects:read / redirects:write

リダイレクトの取得 / 作成・更新・削除・並べ替え

audit-logs:read

監査ログの取得

approvals:write

承認フローの操作(POST /entries/{id}/approvals)

backups:write

データベースのバックアップのジョブ

imports:write

エントリーの CSV インポートのジョブ

exports:write

WordPress(WXR)形式のエクスポートのジョブ

static-exports:write

静的書き出しのジョブ

plugins:write

プラグインの有効化・無効化のジョブ

プラグインが追加したスコープも、発行画面に並びます(プラグインから 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 を渡さず、公開は人が管理画面で行う、という分担ができます。

スコープの選び方

用途

選ぶスコープ

サイトのデータを読むだけ(集計・バックアップの確認・静的サイトの生成など)

read

外部のシステムから記事を下書きで入稿し、公開は人が行う

entries:write と media:write(カテゴリーの一覧を読むなら categories:read も)

外部のシステムから記事を公開まで自動で行う

entries:write・entries:publish・media:write

サイトの構成(カテゴリー・モジュール ID・ルール)も含めて作る

write(設定キーも変えるなら configs:write)

リダイレクトを一括で登録する

redirects:write

監査ログを外部のログ基盤へ取り込む

audit-logs:read

夜間にバックアップを取る

backups:write

管理画面の権限との関係

操作が許されるのは、トークンのスコープと、管理画面と同じ権限の判定(ブログ・カテゴリー・ロールによる権限、承認フロー、編集ロック)の両方を満たしたときだけです。スコープで権限が広がることはありません。

足りないもの

ステータス

code

トークンのスコープ

403

insufficient_scope

管理画面の権限

403

forbidden

閲覧の権限(非公開のエントリー・権限の無いブログのカテゴリーなど)

404

not_found

閲覧する権限の無いリソースは、存在しないものと同じく 404 を返します。存在を知らせないためです。

組み合わせの例

ユーザーの権限

トークンのスコープ

できること

できないこと(応答)

編集者

entries:write

下書き・非公開のエントリーの作成。ブログのエントリー(ほかのユーザーのものを含む)のうち、公開中でないものの更新とゴミ箱への移動。公開中のエントリーの新しいバージョンの作成(POST /entries/{id}/revisions)。エントリーの一覧・取得

公開・非公開の切り替え、公開での作成、公開中のエントリーの更新・削除(403 insufficient_scope、要るスコープは entries:publish)。メディアのアップロード(403 insufficient_scope、media:write)。カテゴリーの作成(403 insufficient_scope、categories:write)

編集者

write・entries:publish

上の行のすべてと、公開・非公開、公開中のエントリーの更新・削除、メディア・カテゴリー・タグの操作

モジュール ID・ルール・コンフィグセットなど、管理画面で管理者だけができる操作(403 forbidden)。設定キーの更新(403 insufficient_scope、configs:write)。ユーザーの取得(403 insufficient_scope、users:read)

投稿者

write・entries:publish

自分のエントリーの作成・更新・公開・削除(管理画面の投稿者と同じ範囲)

ほかのユーザーのエントリーの更新(403 forbidden)や、閲覧できない下書きの取得(404 not_found)。カテゴリーの作成(403 forbidden)

管理者

read

強い権限を除く、すべてのリソースの読み取り

書き込みすべて(403 insufficient_scope)。ユーザー・監査ログなど強い権限の読み取り(403 insufficient_scope)

読者(既定の設定)

—

—

トークンを発行できません。「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 のトークンで使うときは無視してかまいません。

認証に失敗したとき

ステータス

code

場面

401

missing_token

トークンが送られていない(ヘッダーが Web サーバーで落とされている場合を含む)

401

invalid_token

トークンが正しくない・失効している

401

token_expired

トークンの有効期限が切れている

401

user_disabled

トークンの持ち主のユーザーが利用できない

403

blog_not_allowed

トークンの持ち主が操作できないブログの URL で呼んだ

403

api_access_not_allowed

このユーザーに 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 で、そのブログでの判定を確かめられます。