APIリファレンス

Push! Passkey APIの正式仕様

このページでは、現在稼働しているPush! Passkeyの実装を正式仕様として、APIの接続先、HTTPメソッド、リクエスト項目、レスポンス項目、ステータス、エラー形式を説明します。

Push! Passkey APIは、登録URL発行、認証URL発行、登録結果照会、認証結果照会の4つで構成されます。

すべてのAPIは、顧客サイトのバックエンドからHTTPSで呼び出します。

現在の正式仕様では、APIキーはHTTPの専用ヘッダーではなく、JSON本文のapi_key項目へ設定します。

APIキーをHTML、JavaScript、data属性、URL、ブラウザへ返すJSONへ含めてはいけません。

• 共通通信仕様
• 登録URL発行API
• 認証URL発行API
• 登録結果照会API
• 認証結果照会API
• statusと判定用フラグ
• HTTPステータス
• 共通エラー形式
• サーバー側からの接続例（PHP例）

1. API一覧

2. 共通通信仕様

HTTPSを使用する

Push! Passkey APIへの接続にはHTTPSを使用します。

TLS証明書の検証と接続先ホスト名の検証を有効にしてください。

HTTPメソッド

すべてのAPIでPOSTを使用します。

Content-Type

Content-Type: application/json
Accept: application/json

文字コード

JSON本文はUTF-8で送信します。

APIキー

APIキーは、管理ツールで対象ドメイン用に発行した値を使用します。

現在の正式仕様では、APIキーをJSON本文のapi_keyへ設定します。

{
	"api_key": "管理ツールで発行したAPIキー"
}

APIキーをHTTPのAuthorizationヘッダーやX-API-Keyヘッダーへ設定する方式ではありません。

タイムアウト

顧客サイト側では、接続タイムアウトと通信全体のタイムアウトを設定してください。

レスポンス

APIレスポンスはJSON形式です。

HTTPステータスが2xxであっても、ok、必要項目、処理状態を確認してください。

3. 登録URL発行API

エンドポイント

POST https://auth.jintec.com/regist_url

用途

顧客サイトのユーザーへ、パスキー登録を開始するための登録URLを発行します。

リクエスト

{
	"api_key": "xxxxxxxxxxxxxxxx",
	"user_key": "customer_user_123",
	"return_page_url": "https://example.com/mypage/passkey"
}

リクエスト項目

成功レスポンス

{
	"ok": true,
	"kind": "regist",
	"user_key": "customer_user_123",
	"tenant_id": 1,
	"domain_id": 10,
	"personal_id": 100,
	"domain_name": "example.com",
	"request_id": "u_1234567890abcdef1234567890abcdef",
	"regist_url": "https://auth.jintec.com/regist?u=u_1234567890abcdef1234567890abcdef",
	"expire_at": "2026-07-17T08:30:00+09:00"
}

レスポンス項目

有効期限

登録URLの有効期限は、発行から10分間です。

期限切れ後は同じURLを再利用せず、新しい登録URLを発行してください。

4. 認証URL発行API

エンドポイント

POST https://auth.jintec.com/auth_url

用途

登録済みパスキーを使った認証を開始するための認証URLを発行します。

リクエスト

{
	"api_key": "xxxxxxxxxxxxxxxx",
	"return_page_url": "https://example.com/login/callback"
}

認証開始時にuser_keyは送信しません。認証成功後、提示されたCredential IDからPush! Passkeyがユーザーを特定します。

リクエスト項目

成功レスポンス

{
	"ok": true,
	"kind": "auth",
	"request_id": "u_1234567890abcdef1234567890abcdef",
	"auth_url": "https://auth.jintec.com/auth?u=u_1234567890abcdef1234567890abcdef",
	"expire_at": "2026-07-17T08:30:00+09:00"
}

レスポンス項目

認証URL発行時点では利用者がまだ特定されていないため、user_key、tenant_id、domain_id、personal_id、domain_nameは返しません。認証成功後、/auth_resultのレスポンスで確認します。

有効期限

認証URLの有効期限は、発行から10分間です。

5. 登録結果照会API

エンドポイント

POST https://auth.jintec.com/regist_result

用途

登録URL発行APIから取得したrequest_idを使い、パスキー登録の処理状態と結果を確認します。

リクエスト

{
	"api_key": "xxxxxxxxxxxxxxxx",
	"request_id": "u_1234567890abcdef1234567890abcdef"
}

リクエスト項目

成功レスポンス

{
	"ok": true,
	"kind": "regist",
	"request_id": "u_1234567890abcdef1234567890abcdef",
	"status": "success",
	"user_key": "customer_user_123",
	"tenant_id": 1,
	"domain_id": 10,
	"personal_id": 100,
	"issued_at": "2026-07-17T08:10:00+09:00",
	"started_at": "2026-07-17T08:10:05+09:00",
	"completed_at": "2026-07-17T08:10:12+09:00",
	"expire_at": "2026-07-17T08:20:00+09:00",
	"return_page_url": "https://example.com/mypage/passkey",
	"return_to": {
		"regist_success": "",
		"regist_failed": "",
		"auth_success": "",
		"auth_failed": ""
	},
	"fallback_url": "/passkey_callback.html",
	"error_code": "",
	"error_message": "",
	"is_completed": true,
	"is_success": true,
	"is_failed": false,
	"is_expired": false
}

6. 認証結果照会API

エンドポイント

POST https://auth.jintec.com/auth_result

用途

認証URL発行APIから取得したrequest_idを使い、パスキー認証の処理状態と結果を確認します。

リクエスト

{
	"api_key": "xxxxxxxxxxxxxxxx",
	"request_id": "u_1234567890abcdef1234567890abcdef"
}

成功レスポンス

{
	"ok": true,
	"kind": "auth",
	"request_id": "u_1234567890abcdef1234567890abcdef",
	"status": "success",
	"user_key": "customer_user_123",
	"tenant_id": 1,
	"domain_id": 10,
	"personal_id": 100,
	"issued_at": "2026-07-17T08:10:00+09:00",
	"started_at": "2026-07-17T08:10:05+09:00",
	"completed_at": "2026-07-17T08:10:12+09:00",
	"expire_at": "2026-07-17T08:20:00+09:00",
	"return_page_url": "https://example.com/login/callback",
	"return_to": {
		"regist_success": "",
		"regist_failed": "",
		"auth_success": "",
		"auth_failed": ""
	},
	"fallback_url": "/passkey_callback.html",
	"error_code": "",
	"error_message": "",
	"is_completed": true,
	"is_success": true,
	"is_failed": false,
	"is_expired": false
}

7. 結果照会レスポンス項目

issued_at、started_at、completed_at、expire_atは、URL発行APIと同じISO 8601形式で返します。日本標準時の場合は2026-09-02T14:34:02+09:00のようにタイムゾーンオフセットを含みます。日時が未設定の項目は空文字列です。

8. status

成功判定

if (
	$response['status'] === 'success'
	&& $response['is_completed'] === true
	&& $response['is_success'] === true
) {
	// 成功時の処理
}

ok=trueは、結果照会API自体が正常に応答したことを示します。

パスキー処理の成功は、statusと判定用フラグで確認してください。

9. 顧客サイトバックエンドエンドポイントのaction

Push! Passkeyの共通JavaScriptから顧客サイトのバックエンドエンドポイントへ送信されるactionは次の4種類です。

10. リダイレクトパラメータ

Push! Passkey認証画面から顧客サイトへ戻る際、次のURLパラメータが使用されます。

これらのURLパラメータだけで成功判定を行わず、顧客サイトのバックエンドから結果照会APIを呼び出してください。

11. 共通エラーレスポンス

形式

{
	"ok": false,
	"error_code": "invalid_api_key",
	"message": "APIキーが正しくありません。"
}

URL発行APIの主なエラー

結果照会APIの主なエラー

12. HTTPステータス

HTTPステータスだけでなく、JSON本文のokとerror_codeも確認してください。

13. cURLによる接続例

認証URL発行

$request_body = [
	'api_key' => $config['api_key'],
	'return_page_url' =>
		'https://example.com/login/callback',
];

$json_body = json_encode(
	$request_body,
	JSON_UNESCAPED_UNICODE
	| JSON_UNESCAPED_SLASHES
	| JSON_THROW_ON_ERROR
);

$curl = curl_init(
	'https://auth.jintec.com/auth_url'
);

curl_setopt_array($curl, [
	CURLOPT_POST => true,
	CURLOPT_RETURNTRANSFER => true,
	CURLOPT_CONNECTTIMEOUT => 5,
	CURLOPT_TIMEOUT => 15,
	CURLOPT_SSL_VERIFYPEER => true,
	CURLOPT_SSL_VERIFYHOST => 2,
	CURLOPT_HTTPHEADER => [
		'Content-Type: application/json',
		'Accept: application/json',
	],
	CURLOPT_POSTFIELDS => $json_body,
]);

$response_body = curl_exec($curl);
$http_status = (int) curl_getinfo(
	$curl,
	CURLINFO_RESPONSE_CODE
);

curl_close($curl);

認証結果照会

$request_body = [
	'api_key' => $config['api_key'],
	'request_id' => $request_id,
];

重要事項

• APIキーはサーバー側の非公開設定または環境変数から取得する
• APIキーをブラウザから受け取らない
• TLS証明書の検証を無効にしない
• HTTPステータスを確認する
• JSON形式と必要項目を確認する
• APIキーや生レスポンスを利用者へ表示しない

14. 実装時の確認事項

• 開発環境と本番環境でAPIキーを分離している
• 対象ドメイン用のAPIキーを使用している
• APIキーをJSON本文へ設定している
• 登録開始時のuser_keyを顧客サイトのバックエンドで決定している
• 認証開始時にはuser_keyを送信していない
• return_page_urlをHTTPS URLに限定している
• URL発行時のrequest_idを保存している
• 登録結果ではuser_keyを開始時の値と照合し、認証結果ではuser_keyから顧客DBのユーザーを特定している
• success時に判定用フラグを確認している
• 同じ成功結果を複数回使用していない
• 認証成功後のセッションを顧客サイト側で発行している

15. 次に確認するページ

エラーコード

各エラーコードの発生条件、利用者向け表示、開発者が確認する項目を案内します。

エラーコードを読む

認証結果の受け取り

request_idの保存、結果照合、セッション発行、結果の再利用防止を確認します。

認証結果の受け取りを読む

トラブルシューティング

HTTP 405、JSONではない応答、APIキー不正、結果を取得できない場合の確認方法を案内します。

トラブルシューティングを読む

まとめ

4つのAPIを顧客サイトのバックエンドから利用する

Push! Passkey APIは、登録URL発行、認証URL発行、登録結果照会、認証結果照会の4つで構成されます。

登録URL発行APIではapi_key、user_key、return_page_urlを、認証URL発行APIではapi_keyとreturn_page_urlを必須項目として設定します。

結果照会APIでは、JSON本文へapi_keyとrequest_idを設定します。

APIキーは顧客サイトのバックエンドだけで保持し、ブラウザへ出力しないでください。

認証結果は、request_id、kind、user_key、status、判定用フラグを確認した後に利用します。