home/運営公式/

アプリ開発者向け認証ガイド

アプリ用の認証キーの配布は準備中です。
アプリ連携の認証APIは実装されていますが、現在は一般向けのキー配布を開始していません。受付開始日や登録方法は、決まり次第案内します。以下は実装されている仕組みの解説です。

あいもげのアプリ連携は、外部ブラウザーで利用者が承認し、アプリ専用の資格を発行する方式です。POST /app-authorizations で開始し、承認後に POST /app-credentials で資格を受け取ります。

このページでいう credential は、認証APIが発行するアプリ専用の秘密の値です。配布アプリに全利用者共通のキーを埋め込む方式ではありません。

準備するもの

項目内容
APIの起点URLAPIドキュメントと運営の案内で確認する接続先
APIバージョンこのガイドでは 2026-08-29
板のslugGET /boards で確認する対象の板。X-Board-Key に指定
clientId運営に登録されたアプリID。現行仕様の初期対象は futacha-aimg
redirectUri承認後にアプリへ戻るURI。運営の登録文字列と完全一致するもの
installationIdインストール単位のUUID。再認証でも維持する

任意のアプリID・戻り先で認証できるわけではありません。戻り先のワイルドカードや動的なポート番号は受け付けません。例に載っているIDやURIを使うだけでは本番利用の登録になりません。

clientId と installationId は公開識別子で、秘密鍵ではありません。

全体の流れ

  1. アプリでstateとPKCE verifierを生成する。
  2. POST /app-authorizations で認証を開始する。
  3. 応答の authorizationUrl を外部ブラウザーで開く。
  4. 利用者がアプリ名を確認して許可する。
  5. 登録済みの戻り先でcodeとstateを受け取る。
  6. POST /app-credentials でcodeを専用資格へ交換する。
  7. APIには x-aimg-token ヘッダーで専用資格を送る。

Cloudflareの確認、ブラウザー用トークンの取得、同意画面はWeb側が担当します。アプリがブラウザーのCookieや投稿トークンをコピーしたり、POST /tokens に架空のmetricsを送ったりする手順ではありません。

1. stateとPKCEを準備する

state は、戻ってきた結果が自分の開始した認証か確認する値です。codeVerifier は、その認証を開始したアプリだけがコードを交換するための秘密の値です。認証のたびに、別々の暗号学的乱数から生成します。

  • state：base64url文字の32〜128文字。
  • verifier：43〜128文字。英数字と -._~ が使える。
  • challenge：verifierのASCIIバイト列のSHA-256を、paddingなしbase64urlにした43文字。
  • codeChallengeMethod：S256。

Node.jsでの生成例です。

import { randomBytes, createHash } from 'node:crypto';

const state = randomBytes(32).toString('base64url');
const codeVerifier = randomBytes(32).toString('base64url');
const codeChallenge = createHash('sha256')
  .update(codeVerifier, 'ascii')
  .digest('base64url');

stateとverifierは進行中の認証に結び付けてアプリ内へ保持します。verifierを開始リクエストやブラウザーを開くURLへ入れないでください。

2. 認証を開始する

POST /app-authorizations
Content-Type: application/json
X-Api-Version: 2026-08-29
X-Board-Key: 対象の板のslug
{
  "clientId": "futacha-aimg",
  "redirectUri": "運営に登録した完全一致のURI",
  "installationId": "00000000-0000-4000-8000-000000000001",
  "state": "生成したstate",
  "codeChallenge": "計算したchallenge",
  "codeChallengeMethod": "S256"
}

説明用の文字列は実際の登録値・生成値に置き換えます。成功時は201で { id, expiresAt, authorizationUrl } が返り、承認要求は10分間有効です。

返された authorizationUrl を外部ブラウザーで開きます。APIとWebのドメインや板の配置が異なることがあるため、承認画面のURLをアプリで独自に組み立てません。

3. ブラウザーで承認する

利用者が公式画面でアプリ名を確認し、許可・拒否・キャンセルを選びます。Web側がCloudflareの確認とブラウザー用認証を行います。

GET /app-authorizations/{id} と POST /app-authorizations/{id}/decision は、この画面のためのAPIです。ブラウザーセッション、CSRF token、正しいOriginが関わるため、アプリやSwagger UIから同意を代行しません。

ブラウザーを閉じた場合にも、アプリ側で待機を終了できるようにしてください。

4. アプリへ戻った結果を確認する

結果戻り先URIのクエリ
許可code=...&state=...
拒否error=access_denied&state=...
キャンセルerror=cancelled&state=...

URLとして解析し、パラメーター順序に依存しないようにします。戻り先のscheme・host・pathとstateを検証し、キャンセル済み・前回・別の認証の結果は採用しません。

codeは承認から60秒間、一度だけ有効です。正常な結果を受け取ったら速やかに交換します。

5. 専用資格へ交換する

POST /app-credentials
Content-Type: application/json
X-Api-Version: 2026-08-29
X-Board-Key: 対象の板のslug
{
  "clientId": "futacha-aimg",
  "redirectUri": "開始時と同じ登録URI",
  "code": "戻り先で受け取ったcode",
  "codeVerifier": "この認証の開始時に保存したverifier"
}

交換にブラウザーのCookieは不要です。成功時は201で { credential, credentialId, expiresAt } が返ります。

credentialはOSの保護された資格情報保存領域へ保存し、不透明な文字列として扱います。ログ・URL・クラッシュレポートへ出力しないでください。ブラウザー用トークン、GROWI Access Tokenとは別の値です。

6. APIを呼び出す

x-aimg-token: 受け取ったcredential
X-Api-Version: 2026-08-29
X-Board-Key: 対象の板のslug

Bearer を付けず、値だけを送ります。別ドメインや添付アップロード先へ資格を自動転送しないでください。

認証しても、BAN・role・板の受付条件・投稿間隔・Altchaは免除されません。GET /client-policy で現在の板の条件を確認し、投稿ごとに未使用のAltchaの解を用意します。

スレ立て・返信には操作ごとのUUIDを requestId として付けます。通信断で結果が分からない場合は同じID・同じ内容を保持し、新しいUUIDで無条件に再送しません。同じ操作の再送では元の完了結果を回復できます。処理中は409 IDEMPOTENCY_IN_PROGRESS、同じIDで別の内容を送ると409 IDEMPOTENCY_CONFLICT です。

期限と接続解除

専用資格は最長21日間で、承認元トークンの有効性やアプリの停止にも影響されます。refresh tokenは発行しません。再認証が必要な場合は、新しいstate・verifierでブラウザー承認からやり直します。

同じアプリ・installationId・承認元の匿名主体で再認証すると、新しい資格の発行時に旧資格が失効します。交換応答を失った場合もcodeを無条件に再利用せず、同じinstallationIdで新しい認証を開始してください。

操作APIと必要な資格
アプリ自身が解除DELETE /app-credentials/current に自分のcredential。成功204
接続済み一覧を取得GET /app-credentials に承認元ブラウザーのトークン。秘密値は返らない
ブラウザーから個別に解除DELETE /app-credentials/{id}。承認元ブラウザーのトークンと正しいOriginが必要

ブラウザーの承認画面をrequestIdなしで開くと、接続済みアプリの確認・取り消し画面を利用できます。一覧APIは、アプリが秘密のcredentialを再取得するためのAPIではありません。

エラーの読み方

HTTP・コード原因と対応
400 APP_NOT_REGISTEREDアプリID・戻り先の不一致や運営停止。登録内容を確認
400 AUTHORIZATION_INVALIDPKCE・CSRF・状態などが不正。古い認証を破棄し再開始
400 AUTHORIZATION_EXPIRED要求・codeが期限切れ。新しいstate・verifierで再開始
401 BROWSER_AUTH_REQUIREDブラウザー側の確認・トークンが不足または失効
409 AUTHORIZATION_CONSUMEDcodeを交換済み。繰り返し交換しない
429 AUTHORIZATION_RATE_LIMITED回数制限。Retry-Afterまで待つ
401 TOKEN_EXPIRED承認元ブラウザートークンが期限切れ。必要に応じて再認証
422 TOKEN_NOT_FOUNDアプリ資格自身の期限切れ・失効・アプリ停止、資格不存在など。無限再試行しない

HTMLのCloudflare確認画面や403はAPIのJSONエラーとは別です。問い合わせ・不具合報告へ接続状況を知らせてください。

Swagger UIは入力と応答を調べるために使えますが、state/verifierの保持、アプリへの復帰、利用者の同意を一括で代行しません。配布開始後、登録済みのアプリと外部ブラウザーで一連の動作を検証してください。

API利用ガイド / Swagger UIの使い方 / 更新日：2026年9月15日