ZTXBAS REST API の概要

ZTXBAS の公開 API は意図的に小規模です。4 種類のリソースに対応する /v1/* 配下のエンドポイント、および認証不要の鍵取得・ヘルスチェック用エンドポイントを含みます。

機械可読な仕様

正規仕様はリポジトリの openapi.yaml です。OpenAPI 3.1 形式で、Swagger Editor や Stoplight、各種コード生成ツールから利用できます。

エンドポイント一覧

メソッド	パス	目的
POST	/v1/users	ユーザー登録とセットアップメール送信
GET	/v1/users	テナント内のユーザー一覧
DELETE	/v1/users	本文中のメールアドレスを指定して登録解除
POST	/v1/origins	オリジンを登録
GET	/v1/origins	登録済みオリジンの一覧
DELETE	/v1/origins/{id}	オリジンを削除
POST	/v1/auth/challenge	認証チャレンジを作成して端末へ通知
GET	/v1/auth/status/{challenge_id}	チャレンジの結果をポーリング
GET	/.well-known/jwks.json	JWT 検証用の公開鍵
GET	/health	認証不要の稼働状態確認

/v1/* へのリクエストには HMAC-SHA256 署名が必要です。HMAC 署名 を参照してください。SDK は署名処理を自動で行います。

認証

すべての /v1/* リクエストには次の 4 つのヘッダーを含めます。

X-Application-ID: app_...
X-Timestamp: 1704067200
X-Nonce: 32-hex-chars
X-Signature: hex(HMAC-SHA256(secret, canonical))

エラー形式

4xx/5xx 応答は共通の JSON 形式です。error はプログラムが参照する安定した識別子で、message は変更される場合がある説明文です。message の文面に依存した分岐は避けてください。

エラーコード	意味
MISSING_AUTH	HMAC ヘッダーのいずれかが欠落
INVALID_SIGNATURE	HMAC 検証失敗
INVALID_TIMESTAMP	タイムスタンプが負数または非整数
TIMESTAMP_EXPIRED	サーバー時刻から ±300 秒の範囲外
INVALID_APPLICATION	不明なアプリケーション ID
BODY_TOO_LARGE	本文が 8 KiB を超過
DUPLICATE_EMAIL	既存メールアドレスの重複登録
UNREGISTERED_ORIGIN	未登録オリジンへのチャレンジ作成
USER_NOT_FOUND	不明なユーザーへの操作
ENROLLMENT_FAILED	登録メールを送信できなかった

{ "error": "UNREGISTERED_ORIGIN", "message": "origin not registered for this application" }

レート制限

この API 概要に記載された v1 インターフェース自体では、レート制限の強制はありません。テナント単位の制限が必要な場合は nginx、Caddy、Cloudflare 等のリバースプロキシで制御してください。推奨構成は ハードニングガイド を参照してください。