API 接続ガイド

本書は first/api 配下の実装に基づく接続手順・パラメータ・レスポンス・エラー確認のまとめです。OpenAPI 定義はリポジトリ内にありません。

INDEX

共通事項
- 環境変数（JWT / OIDC）
- アプリ・DB
接続の流れ（概要）
エンドポイント一覧とパラメータ定義表
レスポンス例
エラー時の確認手順
参考実装パス

共通事項

項目	内容
ベースURL	デプロイ先のオリジンに続けて `/api/...`（例: `https://<ホスト>/api/member/auth/`）
旧パス	`/api/auth/` 等は `/api/member/...` へのシムとして併存する場合があります
レスポンス形式	本文は JSON。多くのエンドポイントは `Content-Type: text/javascript; charset=utf-8` を返します
HTTPメソッド	実装は `php://input` または `$_POST` / `$_GET` ベースです。クライアントは各表の推奨メソッドで送ってください

環境変数（JWT / OIDC）

変数名	必須	説明
`JWT_SECRET`	JWT利用時は必須	アクセストークン署名用（十分に長いランダム文字列）
`JWT_ISS`	任意	issuer。未設定時は `https://lnx.digital`
`JWT_ACCESS_TTL`	任意	アクセストークン有効秒数（数字のみ）。未設定時は `900`
`JWT_REFRESH_TTL`	任意	リフレッシュトークン有効秒数。未設定時は `1209600`（14日相当）
`OIDC_ISSUER`	OIDC利用時は必須	IdP の issuer
`OIDC_CLIENT_ID`	OIDC利用時は必須	クライアントID
`OIDC_REDIRECT_URI`	OIDC利用時は必須	リダイレクトURI
`OIDC_CLIENT_SECRET`	任意	コンフィデンシャルクライアント用
`OIDC_SCOPES`	任意	未設定時は `openid profile email`

アプリ・DB

PHP が first をドキュメントルート（またはそのサブパス）として解決できること
first/dba/config.php 等による DB 接続が有効であること（会員系・JWT リフレッシュは DB を使用）

接続の流れ（概要）

会員サイト向け: ドメイン/サイトコードでサイトを特定し、メールとパスワードで認証する（member/auth）。成功時は code に view 用 ID が入ります。
コンソール（管理）向け JWT: JSON で clientId / loginID / password を jwt/loginConsole.php に送り、accessToken と refreshToken を取得します。
トークン更新: refreshToken を jwt/refresh.php に POST してローテーションします。
失効: refreshToken または Authorization: Bearer <accessToken> を jwt/revoke.php に渡します。
OIDC: oidc/start.php で authorizeUrl を取得 → ブラウザで IdP に遷移 → コールバック後に oidc/callback.php に code / state / stateToken を POST して JWT を取得します。

エンドポイント一覧とパラメータ定義表

会員: 認証（JSON）

URL: POST /api/member/auth/（旧: POST /api/auth/）

リクエストヘッダー: Content-Type: application/json

パラメータ	必須	型	説明
`domain`	はい	string	サイト識別に使用するドメイン
`code`	はい	string	サイト識別に使用するコード
`email`	はい	string	ログインID（メール）
`password`	はい	string	パスワード

レスポンスフィールド

フィールド	説明
`action`	固定で `signin`
`result`	`success` または `error`
`errorCode`	失敗時の理由コード（成功時は空文字の場合あり）
`code`	成功時: view 用 ID（トークン文字列）。失敗時は空
`nextURL`	サイト登録用コールバック URL（無ければ空文字）

会員: からあげ等（フォームPOST）

URL: POST /api/member/authKaraage/（旧: POST /api/authKaraage/）

リクエスト: application/x-www-form-urlencoded または multipart/form-data（$_POST）

パラメータ	必須	型	説明
`siteID`	はい	string	クライアント側サイトコード（グループ解決に使用）
`loginID`	はい	string	ログインID
`password`	はい	string	パスワード

レスポンスフィールド

フィールド	説明
`action`	実装上 `singin`（typo）
`result`	`success` または `error`
`errorCode`	失敗理由（`PostFieldError1`〜`6`, `SiteCodeError3`, `CannotSignIn`, `NotRegist` 等）
`code`	成功時: view 用 ID
`nextURL`	現状ほぼ未使用（空）

会員: メール取得

URL: POST /api/member/user/（旧: POST /api/user/）

パラメータ	必須	型	説明
`siteCode`	はい	string	サイトクライアントコード
`userSub`	はい	string	ユーザーの view コード

レスポンスフィールド

フィールド	説明
`result`	成功時 `OK`、失敗時 `error`
`errorCode`	失敗理由コード
`mailAddress`	成功時: メールアドレス

会員: グループユーザートークン検証

URL: POST /api/member/groupUserAuth/（旧: POST /api/groupUserAuth/）

パラメータ	必須	型	説明
`siteCode`	はい	string	サイトクライアントコード
`userToken`	はい	string	検証するトークン

レスポンスフィールド

フィールド	説明
`result`	成功時 `OK`、失敗時 `error`
`errorCode`	失敗理由（`inValidToken`, `tokenRequired`, `siteCodeIsRequired`, `inValidCode-<siteID>_<siteCode>` 等）
`subID`	成功時: view コード

会員: メッセージ送信（JSON）

URL: POST /api/member/sendMessage/（旧: POST /api/sendMessage/）

リクエストヘッダー: Content-Type: application/json

パラメータ	必須	型	説明
`code`	はい	string	サイトクライアントコード（`checkSiteByClientID`）
`subID`	はい	string	ユーザーの view コード
`subject`	はい	string	件名
`message`	はい	string	本文

レスポンスフィールド

フィールド	説明
`action`	`sendMessage`
`result`	`success` または `error`
`errorCode`	失敗理由
`code`, `nextURL`	互換用（送信APIでは実質未使用）

JWT: コンソールログイン

URL: POST /api/jwt/loginConsole.php または POST /api/jwt/login.php
（実体: first/api/admin/jwt/loginConsole.php）

リクエストヘッダー: Content-Type: application/json

パラメータ	必須	型	説明
`clientId`	はい	string	`digitalnx` またはサイト/グループのクライアントID
`loginID`	はい	string	メール等のログインID
`password`	はい	string	パスワード
`redirectURL`	任意	string	ログイン後の遷移先。`notDirected` の場合は既定ダッシュボード扱い

レスポンスフィールド

フィールド	説明
`action`	`checkMailExists`
`result`	`success` または `error`
`state`	現状は空文字で返る実装
`errorCode`	失敗時コード
`nextPage`	コンソール/コールバック用の次URL（クライアント種別により内容が異なる）
`accessToken`	成功時のみ: JWT 文字列
`refreshToken`	成功時のみ: 不透明リフレッシュトークン
`expiresIn`	成功時のみ: アクセストークンの有効秒数
`tokenType`	成功時: `Bearer`

主な errorCode（実装より）

errorCode	意味
`PostFieldError`	`clientId` / `loginID` / `password` の不足
`needSignUp`	メイン未登録
`invalidKey`	サイトID解決失敗
`JWT_SECRET_UNSET`	環境変数 `JWT_SECRET` 未設定
`CannotResolveUser`	認証は成功したがユーザーIDを解決できない（グループ等の分岐）

※ 認証失敗で result が error かつ errorCode が空のケースがあります（実装依存）。

JWT: リフレッシュ

URL: POST /api/jwt/refresh.php

リクエストヘッダー: Content-Type: application/json

パラメータ	必須	型	説明
`refreshToken`	はい	string	ログインまたは直前の refresh で得た生トークン

レスポンスフィールド

フィールド	説明
`action`	`jwtRefresh`
`result`	`success` または `error`
`errorCode`	失敗理由
`accessToken`, `refreshToken`, `expiresIn`, `tokenType`	成功時のみ（`refreshToken` はローテーションされ新しい値）

errorCode（refresh）

errorCode	意味
`PostFieldError`	初期状態（未使用に近い）
`refreshTokenRequired`	`refreshToken` が空
`JWT_SECRET_UNSET`	`JWT_SECRET` 未設定
`invalid_refresh`	トークンがDBに存在しない
`refresh_reuse`	失効済みトークンの再利用検知
`refresh_expired`	期限切れ

JWT: 失効

URL: POST /api/jwt/revoke.php

リクエストヘッダー: Content-Type: application/json
任意ヘッダー: Authorization: Bearer <accessToken>

パラメータ	必須	型	説明
`refreshToken`	条件付き	string	指定時は該当ファミリーを失効

ルール: refreshToken と Bearer の少なくとも一方が必要。両方指定可能。

レスポンスフィールド

フィールド	説明
`action`	`jwtRevoke`
`result`	通常 `success`、パラメータ不正やトークン不正で `error`
`errorCode`	失敗時
`revoked`	`none` / `family` / `user_all` / `family_and_user`

errorCode

errorCode	意味
`refreshToken_or_bearer_required`	両方とも欠落
`invalid_refresh_token`	refresh のみ指定したがハッシュ不一致
`invalid_access_token`	Bearer が無効
`JWT_SECRET_UNSET`	Bearer 検証時にシークレット未設定

JWT: パスワード変更

URL: POST /api/jwt/changePassword.php

リクエストヘッダー:

Content-Type: application/json
Authorization: Bearer <accessToken>（必須）

パラメータ	必須	型	説明
`currentPassword`	はい	string	現パスワード
`newPassword`	はい	string	新パスワード（現パスワードと同一不可）

レスポンスフィールド

フィールド	説明
`action`	`jwtChangePassword`
`result`	`success` または `error`
`errorCode`	失敗理由

errorCode

errorCode	意味
`bearer_required`	Authorization 欠落
`PostFieldError`	パスワード項目欠落
`password_unchanged`	新旧が同一
`JWT_SECRET_UNSET`	シークレット未設定
`invalid_access_token`	JWT 不正・期限切れ等
`auth_failed`	現パスワード不一致・ユーザー解決失敗・更新検証失敗

成功時は当該ユーザーの全リフレッシュトークンが失効します。

OIDC: 開始

URL: POST /api/jwt/oidc/start.php

パラメータ	必須	型	説明
`clientId`	はい	string	JWT ログインと同様のクライアントID
`redirectURL`	任意	string	ログイン完了後の `nextPage` に使われる候補

レスポンス（成功時）

フィールド	説明
`action`	`oidcStart`
`result`	`success`
`state`	IdP に渡す state
`stateToken`	サーバ側検証用トークン（callback とセットで使用）
`authorizeUrl`	ブラウザで開く認可エンドポイントの完全 URL
`expiresIn`	`300`（state 関連の有効目安・秒）

errorCode: oidcDisabled, PostFieldError, oidcStartFailed

OIDC: コールバック（トークン交換）

URL: POST /api/jwt/oidc/callback.php

パラメータ	必須	型	説明
`code`	はい	string	IdP からの認可コード
`state`	はい	string	start 時に発行した state
`stateToken`	はい	string	start 時に発行した stateToken

成功時は JWT ログインと同様に accessToken, refreshToken, expiresIn, tokenType, nextPage が返ります。

errorCode: oidcDisabled, PostFieldError, JWT_SECRET_UNSET, ユーザーマッピング失敗時は resolve_oidc_admin_user の結果、oidcCallbackFailed 等

管理: メールテスト

URL: GET /api/admin/test.php（旧: GET /api/test.php）

パラメータ	必須	型	説明
`mail`	はい	string	クエリ `?mail=`

レスポンス: Content-Type: application/json — ユーザー情報の連想配列、または {"error":"not found"}。欠落時は HTTP 400 と {"error":"Specify mail address: ?mail="}。

レスポンス例

会員認証成功

{
  "action": "signin",
  "result": "success",
  "errorCode": "",
  "code": "<viewIDトークン>",
  "nextURL": ""
}

会員認証失敗（ドメイン不正）

{
  "action": "signin",
  "result": "error",
  "errorCode": "invalidDomain",
  "code": "",
  "nextURL": ""
}

JWT ログイン成功

{
  "action": "checkMailExists",
  "result": "success",
  "state": "",
  "errorCode": "",
  "nextPage": "https://lnx.digital/console/dashboard/",
  "accessToken": "<JWT>",
  "refreshToken": "<opaque>",
  "expiresIn": 900,
  "tokenType": "Bearer"
}

JWT リフレッシュ成功

{
  "action": "jwtRefresh",
  "result": "success",
  "errorCode": "",
  "accessToken": "<新JWT>",
  "refreshToken": "<新opaque>",
  "expiresIn": 900,
  "tokenType": "Bearer"
}

JWT リフレッシュ失敗（期限切れ）

{
  "action": "jwtRefresh",
  "result": "error",
  "errorCode": "refresh_expired",
  "accessToken": "",
  "refreshToken": "",
  "expiresIn": 0,
  "tokenType": "Bearer"
}

会員メール取得成功

{
  "result": "OK",
  "errorCode": "",
  "mailAddress": "user@example.com"
}

OIDC start 成功（概念例）

{
  "action": "oidcStart",
  "result": "success",
  "errorCode": "",
  "state": "<state>",
  "stateToken": "<stateToken>",
  "authorizeUrl": "https://idp.example/authorize?...",
  "expiresIn": 300
}

エラー時の確認手順

1. HTTP ステータスだけ見ていないか

多くの API はエラーでも HTTP 200 のまま JSON で result: error を返します。クライアントは 本文の result / errorCode を必ず解釈してください。

2. 会員系で `PostFieldError` / `siteCodeRequired` 等

確認項目	対応
JSON API にフォームだけ送っている	`Content-Type: application/json` と JSON 本文（`member/auth`, `member/sendMessage`）
`member/user` に JSON を送っている	`application/x-www-form-urlencoded` で `siteCode`, `userSub`
必須キーの綴り	表の名前と完全一致（大文字小文字含む）

3. `invalidDomain` / `invalidKey`（member/auth）

domain と code が DB 上のサイト定義と一致するか
サイト側の登録・キー配布ミスがないか

4. `CannotSignIn` / 認証失敗

メール・パスワードの誤り、未登録
JWT ログインで needSignUp: メイン登録フローが必要

5. `JWT_SECRET_UNSET`

サーバ環境に JWT_SECRET を設定し PHP から getenv('JWT_SECRET') で見えることを確認
設定変更後は PHP-FPM / Apache の再起動が必要な場合あり

6. JWT `invalid_access_token` / `bearer_required`

確認項目	対応
ヘッダー形式	`Authorization: Bearer <1行のJWT>`（`Bearer` の前後スペースは実装で許容）
期限切れ	`refreshToken` で `jwt/refresh.php` を呼び再取得
時刻ずれ	NTP・サーバ時刻のずれが大きいと検証失敗の原因になり得ます

7. refresh で `refresh_reuse` / `invalid_refresh`

同一 refresh を二重送信していないか（ローテーション後は旧トークン無効）
失効・期限切れ後に古いトークンを使っていないか
refresh_reuse はセキュリティ上、ファミリー単位で失効が進む実装です。全セッションを切りたい場合は revoke を検討

8. `sendMessage` で `sendFailed`

AWS SES 等の送信設定・権限・レート制限
noMailAddress: ユーザーにメールが未設定

9. OIDC で `oidcDisabled` / `oidcStartFailed` / `oidcCallbackFailed`

必須環境変数が揃っているか（OidcService の要件）
OIDC_REDIRECT_URI が IdP 登録と完全一致するか
state / stateToken の有効期限（start から 300 秒目安）内に callback しているか
IdP の code が一度きりであること（再送不可）

10. 管理テスト API が 400

GET で ?mail= を付けているか

参考実装パス

種別	パス
会員 API	`first/api/member/*/index.php`
JWT API	`first/api/admin/jwt/.php`, `first/api/admin/jwt/oidc/.php`
公開シム	`first/api/jwt/.php`, `first/api/auth/.php` 等
JWT ロジック	`first/lib/JwtService.php`, `first/models/JwtRefreshModel.php`
コンソールログイン解決	`first/auth/lib/resolveConsoleLogin.php`
OIDC	`first/lib/OidcService.php`, `first/lib/OidcLoginState.php`
コンソール向けドキュメント・API設定	`first/console/siteDetail/`（API連携設定ブロック）、`first/console/siteDetail/documents/`

API 接続ガイド

共通事項

環境変数（JWT / OIDC）

アプリ・DB

接続の流れ（概要）

エンドポイント一覧とパラメータ定義表

会員: 認証（JSON）

会員: からあげ等（フォームPOST）

会員: メール取得

会員: グループユーザートークン検証

会員: メッセージ送信（JSON）

JWT: コンソールログイン

JWT: リフレッシュ

JWT: 失効

JWT: パスワード変更

OIDC: 開始

OIDC: コールバック（トークン交換）

管理: メールテスト

レスポンス例

会員認証成功

会員認証失敗（ドメイン不正）

JWT ログイン成功

JWT リフレッシュ成功

JWT リフレッシュ失敗（期限切れ）

会員メール取得成功

OIDC start 成功（概念例）

エラー時の確認手順

1. HTTP ステータスだけ見ていないか

2. 会員系で PostFieldError / siteCodeRequired 等

3. invalidDomain / invalidKey（member/auth）

4. CannotSignIn / 認証失敗

5. JWT_SECRET_UNSET

6. JWT invalid_access_token / bearer_required

7. refresh で refresh_reuse / invalid_refresh

8. sendMessage で sendFailed

9. OIDC で oidcDisabled / oidcStartFailed / oidcCallbackFailed

10. 管理テスト API が 400

参考実装パス

2. 会員系で `PostFieldError` / `siteCodeRequired` 等

3. `invalidDomain` / `invalidKey`（member/auth）

4. `CannotSignIn` / 認証失敗

5. `JWT_SECRET_UNSET`

6. JWT `invalid_access_token` / `bearer_required`

7. refresh で `refresh_reuse` / `invalid_refresh`

8. `sendMessage` で `sendFailed`

9. OIDC で `oidcDisabled` / `oidcStartFailed` / `oidcCallbackFailed`