API リファレンス
ベース URL は https://api.sealgate.jp/v1。すべて JSON で、キーは snake_case です。
管理画面の操作は 管理画面の使い方 をご覧ください。
概要
パスキーの登録とログインは、どちらも「options を取る → ブラウザで認証システムを動かす → response を verify に送る」の 2 段です。ブラウザ側はブラウザ SDK が行い、開発者のサーバーは SDK から届いた JSON に API キーを付けて SealGate に中継します。API キーはブラウザに出しません。
- ブラウザ: sg.login() → 開発者のサーバー (optionsUrl)
- 開発者のサーバー: POST /v1/login/options → challenge_id と options を SDK に返す
- ブラウザ: 認証システムで署名 → 開発者のサーバー (verifyUrl)
- 開発者のサーバー: POST /v1/login/verify → external_id を受け取り、自分のセッションを発行する
認証
管理画面で発行した API キーを Authorization ヘッダーに付けます。キーはプロジェクトの環境 (本番・テスト。rp_id の単位) ごとです。API ではこの環境をアプリ (app) と呼びます。本番環境のキーは sk_live_、テスト環境のキーは sk_test_ で始まります。テスト環境の利用者は料金 (MAU) の対象外です。
Authorization: Bearer sk_live_...
Content-Type: application/json登録
POST/v1/register/options
| 名前 | 型 | 説明 |
|---|---|---|
external_id必須 | string | 開発者側の利用者 ID (200 文字まで)。SealGate は external_id と display_name を保存するため、メールアドレスではなく個人を表さない ID (内部の番号やランダムな ID) を推奨 |
display_name必須 | string | 認証ダイアログに出す名前 (ニックネームやメールアドレス)。渡した値をそのまま保存し、管理画面に出す。同じ external_id の 2 本目以降の登録では、保存している値は変わらない (変えるときは PATCH /v1/users/{external_id}) |
signed_in | boolean | 既に鍵を持つ利用者に鍵を足すときに true。開発者のサーバーがログイン済みの本人であることを確認したうえで付ける |
recovery_token | string | 端末をなくした利用者が再登録するときの復旧トークン (/v1/recovery/start で発行) |
既に鍵を持つ利用者には、signed_in: true か recovery_token のどちらかが必要です。どちらも無い場合は 403 (recovery_not_allowed) を返します。signed_in はブラウザから届いた値をそのまま使わず、開発者のサーバーのセッションで決めてください。既存の鍵は options.excludeCredentials に入るため、同じ認証システムでの二重登録は認証システムが受け付けません。 authenticatorSelection.residentKey と userVerification はアプリの設定 (resident_key・user_verification) の値です。attestation は none 固定で、認証システムの機種の証明 (attestation) は求めず、検証もしません。端末の一覧の aaguid は認証システムが申告した値で、SealGate は確かめていません。
応答 (options は WebAuthn の PublicKeyCredentialCreationOptions):
{
"challenge_id": "chl_01j8x2k9m4n5p6q7r8s9t0v1w2",
"end_user_id": "eu_01j8x2k9m4n5p6q7r8s9t0v1w2",
"options": {
"rp": { "id": "example.jp", "name": "Example" },
"user": { "id": "…", "name": "taro@example.jp", "displayName": "taro@example.jp" },
"challenge": "…",
"pubKeyCredParams": [
{ "type": "public-key", "alg": -8 },
{ "type": "public-key", "alg": -7 },
{ "type": "public-key", "alg": -257 }
],
"attestation": "none",
"authenticatorSelection": { "residentKey": "preferred", "userVerification": "preferred" },
"timeout": 300000
}
}POST/v1/register/verify
| 名前 | 型 | 説明 |
|---|---|---|
challenge_id必須 | string | options で受け取った値。1 回限り、5 分で失効 |
response必須 | object | SDK (認証システム) が返した RegistrationResponseJSON をそのまま |
name | string | 端末の呼び名 (64 文字まで。超えた分は切り詰める)。SDK の sg.register({ name }) の name は verifyUrl への POST に入るので、開発者のサーバーがここへ渡す |
応答 (201):
{
"credential_id": "crd_01j8x2k9m4n5p6q7r8s9t0v1w2",
"end_user_id": "eu_01j8x2k9m4n5p6q7r8s9t0v1w2"
}ログイン
POST/v1/login/options
| 名前 | 型 | 説明 |
|---|---|---|
external_id | string | 指定するとその利用者の鍵だけを許可する。省略すると端末に保存された鍵から選ぶ (利用者名を入れないログイン) |
応答 (options は PublicKeyCredentialRequestOptions):
{
"challenge_id": "chl_01j8x2k9m4n5p6q7r8s9t0v1w3",
"options": {
"rpId": "example.jp",
"challenge": "…",
"allowCredentials": [{ "type": "public-key", "id": "…", "transports": ["internal"] }],
"userVerification": "preferred",
"timeout": 300000
}
}POST/v1/login/verify
| 名前 | 型 | 説明 |
|---|---|---|
challenge_id必須 | string | options で受け取った値 |
response必須 | object | SDK が返した AuthenticationResponseJSON をそのまま |
応答。以後のセッション発行は開発者側で行います:
{
"end_user_id": "eu_01j8x2k9m4n5p6q7r8s9t0v1w2",
"external_id": "user-123",
"credential_id": "crd_01j8x2k9m4n5p6q7r8s9t0v1w2",
"user_verified": true,
"password_allowed": true
}password_allowed は、このパスキーのログインが成功したときの応答にだけ含まれます。値はアプリの「パスワードでのログインの期限」(password_coexist_until、管理画面の環境の設定で設定) だけで決まり、期限を過ぎると false、期限が無いか期限前なら true です (利用者ごとの値ではありません)。管理画面で入れる期限は日付で、その日の終わり (日本時間の 24:00) までは true です。API の password_coexist_until はその時刻を返します (2026-12-31 なら 2026-12-31T15:00:00.000Z)。パスワードのログインは SealGate を通らないため、SealGate はパスワードのログインを止めません。パスワードのフォームの側で判断するときは、GET /v1/apps/{app_id} の password_coexist_until と、GET /v1/users/{external_id}/credentials の有効な鍵の有無を開発者のサーバーで確かめます。
端末 (パスキー)
GET/v1/users/{external_id}/credentials
応答:
{
"end_user_id": "eu_01j8x2k9m4n5p6q7r8s9t0v1w2",
"data": [
{
"id": "crd_01j8x2k9m4n5p6q7r8s9t0v1w2",
"name": "iPhone",
"transports": ["internal", "hybrid"],
"aaguid": "fbfc3007-154e-4ecc-8c0b-6e020557d7bd",
"backup_eligible": true,
"backed_up": true,
"created_at": "2026-09-01T02:15:00Z",
"last_used_at": "2026-09-22T09:40:12Z",
"revoked_at": null
}
]
}PATCH/v1/credentials/{credential_id}
PATCH/v1/users/{external_id}/credentials/{credential_id}
| 名前 | 型 | 説明 |
|---|---|---|
name必須 | string | 端末の呼び名 (1〜64 文字)。前後の空白と制御文字は取り除く |
端末の呼び名を変えます。応答は一覧の data と同じ形の 1 件です。失効済みの鍵と、external_id を指定した場合にその利用者の鍵でないものは 404 (not_found) を返します。
DELETE/v1/credentials/{credential_id}
鍵を 1 本失効します。
PATCH/v1/users/{external_id}
| 名前 | 型 | 説明 |
|---|---|---|
display_name必須 | string | 新しい表示名 (1〜64 文字) |
SealGate が持つ利用者の表示名を変えます (管理画面や利用者の一覧に出る値)。同じ external_id で 2 本目以降のパスキーを登録しても表示名は変わらないため、変えるときはこれを使います。利用者の端末に保存されたパスキーの名前は変わりません。利用者がいなければ 404 (not_found) を返します。
{
"end_user_id": "eu_01j8x2k9m4n5p6q7r8s9t0v1w2",
"external_id": "user_123",
"display_name": "taro"
}POST/v1/users/{external_id}/revoke
利用者の鍵をすべて失効します (乗っ取り時など)。利用者と監査ログは残ります。
{ "end_user_id": "eu_01j8x2k9m4n5p6q7r8s9t0v1w2", "revoked": 2 }DELETE/v1/users/{external_id}
利用者を削除します (退会や個人情報の削除依頼)。鍵、登録とログインの challenge、復旧トークン、表示名を削除します。監査ログは件数と時刻を残し、end_user_id を deleted に、鍵の ID・IP・User-Agent・detail を空にします。取り消せません。同じ external_id で登録し直すと別の利用者になります。
{
"end_user_id": "eu_01j8x2k9m4n5p6q7r8s9t0v1w2",
"deleted": true,
"credentials_deleted": 2
}復旧
端末をなくした利用者の再登録です。本人確認は開発者側で済ませ、その後にこの API を呼びます。SealGate は 15 分有効の復旧トークンを返すだけで、本人確認は行いません。
POST/v1/recovery/start
| 名前 | 型 | 説明 |
|---|---|---|
external_id必須 | string | 利用者 ID |
reason | string | 監査ログに残す理由 (例: 窓口で本人確認) |
応答。recovery_token を /v1/register/options に渡します:
{
"recovery_token": "rt_…",
"expires_at": "2026-09-22T10:00:00Z"
}アプリの設定
GET/v1/apps/{app_id}
応答。app_id は API キーのアプリと一致している必要があります:
{
"id": "app_01j8x2k9m4n5p6q7r8s9t0v1w6",
"name": "Example",
"rp_id": "example.jp",
"rp_name": "Example",
"origins": ["https://example.jp"],
"resident_key": "preferred",
"user_verification": "preferred",
"password_coexist_until": null,
"webhook_url": null
}PATCH/v1/apps/{app_id}
| 名前 | 型 | 説明 |
|---|---|---|
resident_key | string | 登録時に認証システムへ求める residentKey。required / preferred / discouraged (既定 preferred) |
user_verification | string | 登録とログインで認証システムへ求めるユーザー確認 (userVerification)。required / preferred (既定 preferred) |
API キーで変更できるのは resident_key と user_verification です (どちらか 1 つ以上を渡す)。rp_id・オリジン・Webhook URL・パスワードでのログインの期限 (password_coexist_until) は管理画面の環境の設定で変更します (オリジンと Webhook URL は、ログイン (OAuth) で繋いだ MCP の update_app でも変更できます)。rp_id を変えると、登録済みのパスキーは使えなくなります (パスキーは登録したときの rp_id に結び付くため)。オリジンに登録できるのは、rp_id のドメインかそのサブドメインの https のオリジン (開発用に http://localhost) と、Android アプリのオリジン (android:apk-key-hash:...) です (「ネイティブアプリ」を参照)。利用者名を入れないログインや入力欄の自動入力だけで運用する場合は resident_key を required にします。user_verification を required にすると、生体認証や PIN でユーザー確認をしていない登録とログインを verification_failed で拒否します。管理画面の環境の設定でも変更できます。
監査ログと使用状況
GET/v1/apps/{app_id}/audit
| 名前 | 型 | 説明 |
|---|---|---|
event | string | 種別で絞る (login.succeeded など)。知らない種別は 400 invalid_request |
since | string | この日時以降。ISO 8601 の日時 (時差を付ける。付けなければ日本時間) か、日付 (YYYY-MM-DD。日本時間のその日の 0:00 から。管理画面の絞り込みと同じ)。読めない値は 400 invalid_request |
limit | number | 件数 (既定 200、最大 1000) |
応答 (新しい順)。ip と user_agent は SealGate が受けたリクエストの送り元の値です。API の呼び出しでは中継する開発者のサーバーの IP と User-Agent (Node.js の fetch なら node) になり、利用者の端末の値ではありません (SDK も利用者の値を SealGate に送りません)。管理画面や MCP での操作は、操作した人の値です。利用者の端末の情報が要る場合は、開発者のサーバーで記録してください:
{
"data": [
{
"id": "log_01j8x2k9m4n5p6q7r8s9t0v1w5",
"event": "login.succeeded",
"ok": true,
"end_user_id": "eu_01j8x2k9m4n5p6q7r8s9t0v1w2",
"credential_id": "crd_01j8x2k9m4n5p6q7r8s9t0v1w2",
"ip": "198.51.100.7",
"user_agent": "node",
"detail": null,
"at": "2026-09-22T09:40:12Z"
}
]
}GET/v1/apps/{app_id}/stats
応答。app_id は API キーのアプリと一致している必要があります。mau と registrations は直近 6 か月 (UTC の暦月、古い月が先、今月は途中まで) の月ごとの配列で、mau はその月にログインした利用者数、registrations は登録の完了数です。logins は直近 30 日のログインの成功と失敗の数、users は利用者数と有効な鍵を持つ利用者数です。transports は有効な鍵の transports ごとの本数で、多い順です (1 本の鍵が複数の transports を持てばそれぞれに数え、申告の無い鍵は unknown):
{
"mau": [
{ "month": "2026-04", "users": 812 },
{ "month": "2026-05", "users": 903 },
{ "month": "2026-06", "users": 1240 },
{ "month": "2026-07", "users": 1388 },
{ "month": "2026-08", "users": 1502 },
{ "month": "2026-09", "users": 1097 }
],
"registrations": [
{ "month": "2026-04", "count": 96 },
{ "month": "2026-05", "count": 120 },
{ "month": "2026-06", "count": 305 },
{ "month": "2026-07", "count": 188 },
{ "month": "2026-08", "count": 142 },
{ "month": "2026-09", "count": 61 }
],
"logins": { "succeeded": 4210, "failed": 38 },
"users": { "total": 1830, "with_passkey": 1502 },
"transports": [
{ "name": "internal", "count": 1420 },
{ "name": "hybrid", "count": 61 },
{ "name": "usb", "count": 21 }
]
}Webhook
管理画面の「環境の設定」で Webhook URL (https) を設定すると、API (/v1) での出来事を Webhook Admin から JSON で POST します。出来事と data は下の表のとおりです。管理画面や MCP で同じ操作をしたときも、API と同じ出来事を同じ data で送ります (管理画面でできるのは鍵の失効と利用者の失効・削除。鍵の名前の変更と復旧トークンの発行は MCP でできます)。受け取れなかった配信は Webhook Admin が再送します。配信の記録と署名の鍵は、環境の設定の「配信の記録と署名の鍵」から開く Webhook Admin の画面で確認できます (MCP では get_webhook_portal)。
POST <webhook_url>
content-type: application/json
webhook-id: msg_...
webhook-timestamp: 1790000000
webhook-signature: v1,<base64>
{ "type": "login.succeeded", "timestamp": "2026-09-22T00:00:00.000Z",
"data": { "app_id": "app_...", "end_user_id": "eu_...", "external_id": "user-123", "credential_id": "crd_..." } }| type | data | 送る場面 |
|---|---|---|
register.completed | { app_id, end_user_id, credential_id } | POST /v1/register/verify で登録が完了した |
register.failed | { app_id, code } | POST /v1/register/verify で応答の検証に失敗した。code は API のエラーコード (主に verification_failed、オリジンの不一致は origin_not_allowed)。challenge が期限切れ・使用済み・不明で 410 を返したときは送らない |
login.succeeded | { app_id, end_user_id, external_id, credential_id } | POST /v1/login/verify でログインが成功した |
login.failed | { app_id, code } | POST /v1/login/verify で失敗した。code は verification_failed・origin_not_allowed・credential_revoked・mau_limit など。410 (challenge_expired) のときは送らない |
credential.revoked | { app_id, end_user_id, credential_id } | DELETE /v1/credentials/{credential_id}、管理画面、MCP の revoke_credential で鍵を 1 本失効した |
user.revoked | { app_id, end_user_id, revoked } | POST /v1/users/{external_id}/revoke、管理画面、MCP の revoke_user で利用者の鍵をすべて失効した。revoked は失効した本数 |
user.updated | { app_id, end_user_id } | PATCH /v1/users/{external_id} か MCP の update_user で表示名を変えた。新しい表示名は載せない (利用者の一覧で引く) |
user.deleted | { app_id, end_user_id, credentials_deleted } | DELETE /v1/users/{external_id}、管理画面、MCP の delete_user で利用者を削除した |
recovery.issued | { app_id, external_id, reason } | POST /v1/recovery/start か MCP の issue_recovery_token で復旧トークンを発行した。reason は渡さなければ null |
credential.renamed | { app_id, end_user_id, credential_id } | PATCH /v1/credentials/{credential_id}、PATCH /v1/users/{external_id}/credentials/{credential_id}、MCP の rename_credential で端末名を変えた。新しい名前は載せない (鍵の一覧で引く) |
署名は webhook-id・webhook-timestamp・webhook-signature ヘッダーに付きます。npm の webhookadmin の Webhook で、受け取った本文をそのまま検証します。出来事の種類は type、中身は data です。webhook-id は出来事ごとに 1 つで、再送でも変わらないので、重複の見分けに使えます。
// npm install webhookadmin
import { Webhook } from 'webhookadmin';
const wh = new Webhook(process.env.SEALGATE_WEBHOOK_SECRET); // whsec_...
// Next.js (App Router): app/sealgate/webhook/route.ts
export async function POST(req) {
let body;
try {
body = await wh.verify(await req.text(), req.headers); // { type, timestamp, data }
} catch {
return new Response(null, { status: 400 });
}
const { type, data } = body; // e.g. type: login.succeeded, data: { app_id, end_user_id, external_id, credential_id }
return new Response(null, { status: 204 });
}レート制限
1 分あたりのリクエスト数の上限は、API キーごとに 600 (Free)、3,000 (従量課金・Enterprise) です。組織のすべての API キーの合計は 1,200 (Free)、6,000 (従量課金・Enterprise) です。超えると 429 (rate_limited) と Retry-After ヘッダーを返します。MCP のバッチは 20 件までで、1 件ずつ数えます。管理画面のログインのリンクのメールは、短い時間に送りすぎると、しばらく送れなくなります。
MCP (AI エージェント)
MCP 対応のエージェント (Claude、Claude Code、Cursor、Codex など) から SealGate を扱えます。クライアントに MCP の URL を追加すると、ブラウザで管理画面のログイン (メール・Google・GitHub・パスキー) と許可の画面が開き、許可したアカウントとして操作します (OAuth 2.1)。はじめての方は、そのログインの画面から登録できます。できることは管理画面と同じ役割 (viewer / developer / admin / owner) で決まります。
MCP: https://api.sealgate.jp/v1/mcp (Streamable HTTP、POST)
スキル: https://sealgate.jp/skill/SKILL.md
プラグイン (Claude Code):
/plugin marketplace add https://sealgate.jp/plugin/marketplace.json
/plugin install sealgate@sealgate
接続だけなら:
claude mcp add --transport http sealgate https://api.sealgate.jp/v1/mcpログイン (OAuth) で使うツール
list_organizations (無ければ create_organization) → list_projects / list_environments で環境の ID (app_id) を得て、環境のツールに渡します。組織のツールには organization_id を渡します。
| 名前 | 型 | 説明 |
|---|---|---|
組織・プロジェクト | organization_id | whoami / list_organizations / create_organization / list_projects / list_environments / list_members / invite_member (admin 以上) |
組織のツール | organization_id | create_app・rename_project (admin 以上) / list_api_keys / revoke_api_key (developer 以上、confirm: true で実行) / get_account / create_checkout・get_billing_portal (owner) |
環境のツール | app_id | get_app / list_users / list_credentials / list_audit / get_stats (viewer 以上)、update_app / set_resident_key / get_webhook_portal / create_api_key / update_user / rename_credential / revoke_credential / revoke_user / issue_recovery_token (developer 以上)、delete_user (admin 以上) |
ガイド・料金 | — | get_integration_guide / list_plans |
create_app で project_id を省くと、本番とテストの 2 つの環境を持つプロジェクトを作ります (テスト環境は rp_id localhost、返り値の test_app_id)。project_id と environment (live / test) を渡すと、そのプロジェクトに無い環境を足します。平文の API キーは create_api_key の応答にだけ含まれます。テスト環境のキーは sk_test_ で始まり、テスト環境の利用者は料金の対象外です。操作は環境の監査ログに、操作した人とクライアントの名前とともに残ります。利用者のパスキー登録とログインはブラウザの認証システムが要るためツールにはなく、ガイドに沿ってコードを書いて組み込みます。
許可したアプリは、管理画面の「アカウントの設定 → 接続中のアプリ」に並び、そこから取り消せます。アクセストークンは 1 時間、リフレッシュトークンは 30 日で、使うたびに新しいものに換わります。一度使ったリフレッシュトークンがもう一度使われると、その接続を取り消します。
OAuth のエンドポイント
GET https://api.sealgate.jp/.well-known/oauth-protected-resource/v1/mcp 保護されたリソースのメタデータ (RFC 9728)
GET https://app.sealgate.jp/.well-known/oauth-authorization-server 認可サーバーのメタデータ (RFC 8414)
POST https://app.sealgate.jp/api/oauth/register 動的クライアント登録 (RFC 7591、公開クライアント)
GET https://app.sealgate.jp/api/oauth/authorize 認可 (code、PKCE は S256 だけ、resource は MCP の URL)
POST https://app.sealgate.jp/api/oauth/token authorization_code / refresh_token
POST https://app.sealgate.jp/api/oauth/revoke 取り消し (RFC 7009)
Authorization の無い POST /v1/mcp → 401
WWW-Authenticate: Bearer resource_metadata="https://api.sealgate.jp/.well-known/oauth-protected-resource/v1/mcp"MCP-Protocol-Version は 2025-11-25 / 2025-06-18 / 2025-03-26 / 2024-11-05 に対応します。
アカウントは管理画面 (https://app.sealgate.jp/signup) で作成してください。メールアドレス・Google・GitHub で登録できます。MCP はログイン (OAuth) で繋いでお使いいただけます。
ブラウザ SDK
https://sealgate.jp/sdk/v1.js (ESM) を読み込むか、npm の sealgate-browser (同じ内容、型付き) を使います。optionsUrl と verifyUrl は開発者のサーバー側の URL で、SDK は kind (register | login) を付けて POST します。
npm install sealgate-browser
import { SealGate, SealGateError } from 'sealgate-browser';import { SealGate } from 'https://sealgate.jp/sdk/v1.js';
const sg = new SealGate({
optionsUrl: '/api/passkey/options',
verifyUrl: '/api/passkey/verify',
});
// 登録 (ログイン済みの画面で。2 本目以降も同じ)
await sg.register({ name: 'この端末' });
// ログイン
const result = await sg.login(); // 端末の鍵から選ぶ
const result2 = await sg.login({ external_id: 'user-123' });入力欄の自動入力 (conditional UI)
mediation: 'conditional' を指定すると、認証ダイアログを出さずに、ユーザー名の入力欄の自動入力にパスキーを出します。入力欄に autocomplete="username webauthn" が必要です。開発者のサーバーは external_id を付けずに /v1/login/options を呼びます。利用者が候補を選ぶまで Promise は解決しないため、画面の表示時に呼び出します。
<input name="username" autocomplete="username webauthn" />
if (await SealGate.conditionalMediationAvailable()) {
sg.login({}, { mediation: 'conditional' })
.then(onSignedIn)
.catch((e) => { if (e.code !== 'aborted') console.error(e); });
}
// ボタンでのログインに切り替えるときや、SPA で画面を離れるとき
SealGate.abort();SealGate.supported() でパスキー対応、SealGate.platformAuthenticatorAvailable() で生体認証の有無、SealGate.conditionalMediationAvailable() で自動入力への対応を確認できます。失敗は SealGateError で投げます。code は cancelled、aborted (SealGate.abort() か次の操作の開始で中断)、already_registered (この認証システムに同じ利用者の鍵がある)、unsupported (非対応、または自動入力の入力欄が無い)、http_error (サーバーが error.code の無いエラーを返した。status に HTTP の状態)、API のエラーコード (サーバーが返した error.code をそのまま) のいずれかです。cancelled は利用者が閉じた・時間切れのほか、ブラウザの例外のうちほかのどれにも当たらないもの (rp_id とページのオリジンが合わないときの SecurityError など) も含みます。元の説明は message に入るので、開発中は message も記録してください。optionsUrl・verifyUrl への通信そのものが失敗したとき (ネットワークの切断など) は、SealGateError ではなく fetch の例外がそのまま投げられます。
サーバー側の実装例
SDK からの POST を受けて SealGate に中継し、verify が通ったらセッションを発行します。
Node.js (Next.js Route Handler)
// app/api/passkey/[step]/route.ts — POST /api/passkey/options と /api/passkey/verify を 1 つで受ける例
const BASE = 'https://api.sealgate.jp/v1';
export async function POST(req, { params }) {
const { step } = await params; // 'options' | 'verify' (Next.js 15 以降 params は Promise)
const body = await req.json(); // { kind, ... } SDK が送る
const user = await currentUser(req); // 開発者側のログイン状態
const payload = step === 'options'
? body.kind === 'register'
// 2 本目以降の追加は signed_in: true。ログイン済みかはサーバーのセッションで決める
? { external_id: user.id, display_name: user.email, signed_in: true }
: { external_id: body.external_id } // 省略可 (自動入力では付けない)
: body.kind === 'register'
// sg.register({ name }) の name (端末の呼び名) も渡す
? { challenge_id: body.challenge_id, response: body.response, name: body.name }
: { challenge_id: body.challenge_id, response: body.response };
const res = await fetch(`${BASE}/${body.kind}/${step}`, {
method: 'POST',
headers: { authorization: `Bearer ${process.env.SEALGATE_API_KEY}`, 'content-type': 'application/json' },
body: JSON.stringify(payload),
});
const json = await res.json();
if (step === 'verify' && body.kind === 'login' && res.ok) {
await createSession(json.external_id); // 開発者側のセッション
}
return Response.json(json, { status: res.status });
}curl
curl -X POST https://api.sealgate.jp/v1/login/options \
-H "Authorization: Bearer sk_live_..." \
-H "Content-Type: application/json" \
-d '{"external_id":"user-123"}'サーバー SDK
サーバーから API を呼ぶ SDK です。登録・ログインの開始と完了、利用者と端末、復旧、監査ログと使用状況、Webhook の署名の検証を扱います。429 の待ちと再試行、エラーの種類ごとの型が入っています。API キーはサーバーだけに置きます。
Node.js
npm install sealgate-serverimport { SealGate, verifyWebhook } from 'sealgate-server';
const sg = new SealGate(process.env.SEALGATE_API_KEY);
const start = await sg.login.options();
const r = await sg.login.verify({ challenge_id, response });
await createSession(r.external_id);
const event = await verifyWebhook(await req.text(), req.headers, process.env.SEALGATE_WEBHOOK_SECRET);Go
go get github.com/shannonllc/sealgate-goimport sealgate "github.com/shannonllc/sealgate-go"
sg, err := sealgate.NewClient(os.Getenv("SEALGATE_API_KEY"))
start, err := sg.Login.Options(ctx, nil)
r, err := sg.Login.Verify(ctx, &sealgate.LoginVerifyParams{ChallengeID: id, Response: resp})
createSession(r.ExternalID)
ev, err := sealgate.VerifyWebhook(body, req.Header, os.Getenv("SEALGATE_WEBHOOK_SECRET"))PHP
composer require shannonllc/sealgateuse SealGate\Client;
use function SealGate\verifyWebhook;
$sg = new Client(getenv('SEALGATE_API_KEY'));
$start = $sg->login->options();
$r = $sg->login->verify(['challenge_id' => $id, 'response' => $response]);
createSession($r['external_id']);
$event = verifyWebhook(file_get_contents('php://input'), $_SERVER, getenv('SEALGATE_WEBHOOK_SECRET'));Python
準備中
ネイティブアプリ
ウェブと同じ rp_id のパスキーを、iOS と Android のアプリからも使えます。サーバーの流れはウェブと同じです。アプリから開発者のサーバーに依頼し、サーバーが /v1/register/options (ログインは /v1/login/options) を呼び、返った options の JSON をアプリが OS の API に渡します。OS が返した応答の JSON をサーバーが /v1/register/verify (ログインは /v1/login/verify) に送ります。API キーはサーバーだけに置きます。
iOS
AuthenticationServices を使います。アプリの Associated Domains に webcredentials:<rp_id> を追加し、rp_id のドメインの /.well-known/apple-app-site-association の webcredentials.apps に <Team ID>.<Bundle ID> を記載します。応答のオリジンは https://<rp_id> のため、許可するオリジンに https://<rp_id> があれば SealGate 側の追加の設定は不要です。
Android
Credential Manager を使います。応答のオリジンは android:apk-key-hash:<アプリの署名証明書の SHA-256 を base64url (パディング無し) にした値> です。署名証明書の SHA-256 のフィンガープリントは、keytool -list -v -keystore <キーストア> の SHA256 の行か、Play Console の「アプリの完全性」→「アプリの署名」で確認します。Play アプリ署名を使う場合は Play が署名に使う証明書の値を使います。デバッグ用とリリース用で値が異なります。管理画面の環境の設定の「オリジン」(MCP では update_app の origins) に android:apk-key-hash:<値> を追加します。フィンガープリント (AB:CD:...) をそのまま入力しても、android:apk-key-hash: の形に変換して保存します。1 つの環境に 10 個まで登録できます。
rp_id のドメインの /.well-known/assetlinks.json に、relation が delegate_permission/common.get_login_creds、target がアプリのパッケージ名と署名証明書の SHA-256 のフィンガープリントの項目を記載します:
[{
"relation": ["delegate_permission/common.get_login_creds"],
"target": {
"namespace": "android_app",
"package_name": "jp.example.app",
"sha256_cert_fingerprints": ["AB:CD:...:EF"]
}
}]rp_id の照合はウェブと同じです (認証器の応答の rp_id が環境の rp_id と一致する必要があります)。許可するオリジンに無いオリジンからの応答は origin_not_allowed (403) を返します。
エラー
形は { "error": { "code", "message" } } です。
| code | HTTP | 意味 |
|---|---|---|
| invalid_request | 400 | パラメータの不足や形式の誤り |
| invalid_api_key | 401 | API キーが無いか、失効している |
| verification_failed | 401 | 署名の検証に失敗した。名乗った利用者と鍵が一致しない場合、rp_id が合わない場合も含む |
| credential_revoked | 403 | 失効した鍵でのログイン |
| origin_not_allowed | 403 | 登録・ログインの応答のオリジン (clientDataJSON の origin) が、アプリの許可するオリジンに無い。環境の設定の許可するオリジンを確かめる |
| recovery_not_allowed | 403 | /v1/register/options で、鍵を持つ利用者の追加登録に signed_in も recovery_token も無い。または recovery_token が無効・期限切れ・使用済み・別の利用者のもの |
| mau_limit | 402 | 支払い方法を登録していない組織が月の MAU の上限 (1,000) に達した。今月はじめてログインする利用者だけが止まる |
| not_found | 404 | 利用者や鍵が無い |
| challenge_expired | 410 | challenge が期限切れ (5 分)、使用済み、または不明 |
| rate_limited | 429 | 短時間に呼びすぎ |
| internal_error | 500 | SealGate 側の障害 |
| unavailable | 503 | 短いメンテナンスの間。Retry-After の秒数のあとでもう一度送る |