API リファレンス

共通の決まり

• ・通信は HTTPS（TLS 1.2 以上）です。クライアントは、tenant-pass の証明書を必ず検証してください。平文の HTTP は試験のためだけのもので、使うには 2 つの設定（insecure_plaintext_http と allow_insecure_plaintext）が必要です。
• ・すべての応答に付くヘッダー: Cache-Control: no-store、Pragma: no-cache、X-Content-Type-Options: nosniff、Content-Security-Policy: default-src 'none'; frame-ancestors 'none'、Referrer-Policy: no-referrer。応答にシークレットが含まれるため、途中のプロキシにもクライアントにも残さないようにしています。
• ・エラーのレスポンスボディは、常に {"error": "<code>"} の形です。失敗の理由は返さず、監査ログに書きます。
• ・POST のボディは、4096 バイトまでの JSON オブジェクトです。未知のフィールド、重複したフィールド、後ろに続く余分なデータは拒否します。ヘッダーは 16 KiB までです。
• ・検査の順序は、URL → メソッド → Content-Type → 同時に処理しているリクエスト数 → アプリケーションの認証 → リクエストボディ → パスまたはチケット → 1 分あたりのテナント数 → ディレクトリ → ストア、です（詳しくは仕組みのページ）。

アプリケーションの認証

POST のエンドポイントは、呼び出したアプリケーションを認証します。方法はアプリトークンとクライアント証明書の 2 つで、両方を求めることもできます。認証できたアプリケーションの名前（apps[].name）は、パスの aud と一致しなければなりません。

POST/v1/credentials

パス（またはジョブチケット）を、テナントの認証情報に交換します。同じウィンドウの中なら、どのレプリカに問い合わせても、どのワーカーが問い合わせても、同じパスワードが返ります。

使う場面

テナントのリクエストを処理するときに、その認証情報をまだ持っていない場合や、refresh_at を過ぎた場合。ジョブチケットを持つワーカーが処理を始めるとき。

認証

必要です（アプリケーションの認証）。

主なエラー

400 invalid_pass・401 unauthorized・403 denied・429 rate_limited・503 unavailable（エラーコード）。

リクエスト

POST /v1/credentials HTTP/1.1
Host: tenant-pass.internal:8443
Authorization: Bearer tpa_9b0Z…
Content-Type: application/json

{"pass": "v4.public.…", "repair": false}

例

curl -s https://tenant-pass.internal:8443/v1/credentials \
  --cacert tenant-pass-ca.pem \
  -H "Authorization: Bearer $APP_TOKEN" \
  -H 'Content-Type: application/json' \
  -d "{\"pass\":\"$PASS\"}"

curl -s https://tenant-pass.internal:8443/v1/credentials \
  --cacert tenant-pass-ca.pem \
  -H "Authorization: Bearer $APP_TOKEN" \
  -H 'Content-Type: application/json' \
  -d "{\"pass\":\"$PASS\",\"repair\":true}"

curl -s https://tenant-pass.internal:8443/v1/credentials \
  --cacert tenant-pass-ca.pem \
  -H "Authorization: Bearer $APP_TOKEN" \
  -H 'Content-Type: application/json' \
  -d "{\"ticket\":\"$TICKET\"}"

curl -s https://tenant-pass.internal:8443/v1/credentials \
  --cacert tenant-pass-ca.pem \
  --cert reports.crt --key reports.key \
  -H 'Content-Type: application/json' \
  -d "{\"pass\":\"$PASS\"}"

レスポンス 200 OK

{
  "tenant": "acme",
  "store": "postgres",
  "host": "pgbouncer.internal",
  "port": 6432,
  "database": "app",
  "username": "t_acme",
  "password": "lRG6msAkg88kIIjJU-N6yWZ6wzx1gQj62GYG71hcgjE",
  "expires_at": "2026-11-03T12:08:59Z",
  "refresh_at": "2026-11-03T12:03:59Z"
}

POST/v1/job-tickets

後から動く処理が認証情報を取れるように、パスを同じテナントのジョブチケットに交換します。設定に job_tickets.signing_key があり、アプリケーションで "jobs": {"issue": true} を有効にしている必要があります。

使う場面

エクスポートやインポートなど、ユーザーのリクエストから始まり、キューに入れて後から動かす処理を登録するとき（ジョブチケット）。

認証

必要です（アプリケーションの認証）。

主なエラー

400 invalid_request・400 invalid_pass・403 denied・429 rate_limited（下の説明と エラーコード）。

curl -s https://tenant-pass.internal:8443/v1/job-tickets \
  --cacert tenant-pass-ca.pem \
  -H "Authorization: Bearer $APP_TOKEN" \
  -H 'Content-Type: application/json' \
  -d "{\"pass\":\"$PASS\",\"ttl\":\"15m\"}"

レスポンス 200 OK

{"ticket": "v4.public.…", "tenant": "acme", "expires_at": "2026-11-03T12:30:00Z"}

• ・テナントは、発行の時点で確かめます（存在し、有効で、そのアプリケーションに許可されていること）。チケットには、正式なテナント ID が書かれます。
• ・チケットの発行も、認証情報と同じ「1 分あたりのテナント数」の制限に数えます。制限をすり抜ける手段にはなりません。
• ・1 つのパスと交換できるチケットは、レプリカごとに 1 枚です。2 回目は 403 denied（監査ログでは pass_already_used）になります。ほかの理由で発行に失敗したときは、そのパスをもう一度使えるので、リトライできます。
• ・アプリケーションでチケットの発行が有効になっていなければ、403 denied（監査ログでは job_issue_not_enabled）になります。そのほかのエラーは /v1/credentials と同じです。

エラーコード

エラーのレスポンスボディは、常に {"error": "<code>"} の形です。400・401・403 は、同じパスで何度試しても成功しない失敗です。クライアントはログに残し、そのリクエストをエラーにしてください。429・503 は、間を空けてリトライしてかまわない失敗です。

監査ログ

リクエストごとに、1 行の JSON を標準出力に書きます。/v1/credentials の記録は "msg":"credential"、/v1/job-tickets の記録は "msg":"job_ticket" です。成功は INFO、クライアント側のエラーは WARN、ディレクトリやストアの問題と安全性の問題（directory_error・store_error・account_refused・clock_skew・timeout・unknown_node・directory_mismatch・sign_error）は ERROR です。

{"time":"2026-11-03T12:00:01Z","level":"INFO","msg":"credential","request_id":"43f007226bb0e766","app":"billing","repair":false,"jti":"hamSSKegCc-kk82SdW2dpw","host":"acme.example.com","tenant":"acme","node":"pg1","account":"t_acme","store":"postgres","window":1993007,"key_id":"k1","changed":true,"expires_at":"2026-11-03T12:08:59Z","result":"ok","duration_ms":7}

アラートを出すべき条件は、運用 › 監視 にあります（account_refused、pass_signature・pass_unknown_key、pass_audience、distinct_tenants など）。

tenant-pass-gateway の応答（forward-auth）

付属のゲートウェイは、プロキシから認可の問い合わせを受けるサービスです。待ち受けるアドレス（既定 127.0.0.1:9180）では、どの URL へのリクエストも認可の問い合わせとして扱います。ヘルスチェック用の URL はないので、必要なら health_listen で別のアドレスを指定し、そこで GET /healthz を受け付けます。リクエストボディは使わず、ヘッダーだけを見ます。

コマンド

ゲートウェイ側のコマンドは tenant-pass-gateway serve -config FILE、tenant-pass-gateway check-config -config FILE、tenant-pass-gateway version です。

Go の pass パッケージ

独自のゲートウェイやスケジューラーでは、github.com/kobesoft-labs/tenant-pass/pass を import すれば、そのまま署名できます。ほかの言語でも、PASETO v4 のライブラリと パスの形式 の仕様に沿って実装できます。その場合は、出力がテストベクターとバイト単位で一致することを確かめてください。

import "github.com/kobesoft-labs/tenant-pass/pass"

s := pass.Signer{KeyID: "gw1", Key: privateKey} // ed25519.PrivateKey
now := time.Now()
p, err := s.Sign(pass.Claims{
    Audience: "billing",
    Host:     "acme.example.com",  // または Tenant: "acme"
    IssuedAt: now,
    Expiry:   now.Add(30 * time.Second),
})

// スケジューラー: ジョブチケット（暗黙のアサーション tenant-pass/v1/job）
t, err := s.SignJob(ctx, pass.JobClaims{Audience: "reports", Tenant: "acme", IssuedAt: now, Expiry: now.Add(time.Hour)})