認証

このガイドでは、Human Dashboard で認証し、すべての Human Token API リクエストで使用する x-unico-accesskey を生成する手順を説明します。

フローは2つのフェーズで構成されます。

認証 — ログインを完了し、アクセストークンを取得します。利用できる認証方法は2つあります。
- 生体認証ログイン — Unico SDK による顔キャプチャ（サインアップとサインインの両方で利用可能）
- メール OTP ログイン — 登録済みのメールアドレスに送信されるワンタイムコード（サインインのみ）
組織の設定 — 会社プロフィールを作成し、アクセスキーを生成します（初回サインアップ時のみ）

認証情報を設定する2つの方法

このガイドの内容はすべて、dashboard.unico.app の Human Dashboard からも実行できます。API 呼び出しは不要です。

オプション	使用するタイミング
ダッシュボード	初回セットアップ、手動でのキーローテーション、随時の管理
API	自動プロビジョニング、CI/CD パイプライン、プログラムによるキー管理

ダッシュボードを使用する

dashboard.unico.app にアクセスします
サインアップまたはサインイン — 生体認証ログイン（顔キャプチャ）またはメール OTP を使用します
組織を作成 — 会社名、国、許可するドメインを入力します
アクセスキーを生成 — Access Keys に移動して Create key をクリックします。キーは一度しか表示されないため、すぐにコピーしてください
ブランチを管理 — Branches でブランチを作成・設定します。各ブランチは独自のアクセスキーを生成します

ダッシュボードで取得するアクセスキーは、すべての API リクエストで使用される x-unico-accesskey と同じものです。2つの方法は完全に互換性があります。

ベース URL

このページのすべてのエンドポイントは Human Dashboard API によって提供されます。Create Process や Get Process などの Human Token API リクエストは、環境に記載されている API ホストに送信されます。

環境	API	ベース URL
本番環境	Human Dashboard API（ログイン、組織、アクセスキー、ブランチ）	`https://api.humantoken.unico.app`

認証方法

認証して authToken を取得する方法は2つあります。

方法	エンドポイント	使用するタイミング
生体認証	`POST /api/console/v1/auth/biometric/sessions`	サインアップ（新規アカウント）またはサインイン（既存ユーザー）
メール OTP	`POST /api/console/v1/auth/email/sessions`	サインインのみ — アカウントが既に存在している必要があります

生体認証ログインの intent

POST /api/console/v1/auth/biometric/sessions の呼び出しでは、必ず intent を指定する必要があります。

`intent`	使用するタイミング	`email` フィールド	`name` フィールド
`LOGIN_INTENT_SIGNUP`	初回登録 — 新しいアカウントを作成する場合	必須	必須
`LOGIN_INTENT_SIGNIN`	既存ユーザー — アカウントが既に存在する場合	使用しない	使用しない
（省略）	`LOGIN_INTENT_SIGNIN` として扱われます	使用しない	使用しない

intent は、セッションをポーリングする際（ステップ2）に行われる検証を制御します。

SIGNUP — その生体認証 ID が既に登録されている場合、ログインを拒否します（アカウントの重複を防止）。
SIGNIN — その生体認証 ID が登録されていない場合、ログインを拒否します（ログインにはアカウントが存在している必要があります）。

フェーズ1 — 認証

ステップ1：生体認証ログインセッションを開始する

SIGNUP（初回登録）

curl -X POST https://api.humantoken.unico.app/api/console/v1/auth/biometric/sessions \
  -H "Content-Type: application/json" \
  -d '{
    "intent": "LOGIN_INTENT_SIGNUP",
    "email": "[email protected]",
    "name": "Jane Doe"
  }'

メールアドレスの一意性

そのメールアドレスで既にアカウントが登録されている場合、リクエストは 400 Bad Request を返します。

レスポンス：

{
  "session": {
    "sessionId": "b3f1a2c4-0000-0000-0000-abcdef012345",
    "link": "",
    "token": ""
  }
}

SIGNUP の場合、レスポンスの link と token フィールドは空です。生体認証キャプチャのリンクは、指定したメールアドレスに送信されます。

SIGNIN（既存ユーザー）

curl -X POST https://api.humantoken.unico.app/api/console/v1/auth/biometric/sessions \
  -H "Content-Type: application/json" \
  -d '{
    "intent": "LOGIN_INTENT_SIGNIN"
  }'

レスポンス：

{
  "session": {
    "sessionId": "b3f1a2c4-0000-0000-0000-abcdef012345",
    "link": "https://humantoken.unico.io/...",
    "token": "eyJhbGciOiJSUzI1NiJ9..."
  }
}

sessionId を保存してください。

SIGNUP：生体認証キャプチャのリンクは、ステップ1で指定したメールアドレスに送信されます。ユーザーに受信トレイを確認してキャプチャを完了するよう依頼してください。
SIGNIN：ブラウザで link を開き、生体認証キャプチャを完了します。

ステップ2：セッションが解決されるまでポーリングする

curl https://api.humantoken.unico.app/api/console/v1/auth/biometric/sessions/b3f1a2c4-0000-0000-0000-abcdef012345

status が終了状態になるまで、2〜3秒ごとにポーリングします。

`status`	`outcome`	意味
`pending`	`pending`	ユーザーがまだキャプチャを完了していません — ポーリングを継続します
`processing`	`pending`	キャプチャは完了し、結果を計算中です — ポーリングを継続します
`completed`	`matched`	ログイン成功 — `authToken` が含まれます
`completed`	`no_match`	生体認証がどのレコードとも一致しませんでした
`completed`	`inconclusive`	キャプチャは成功しましたが、判定できませんでした
`expired`	—	リンクの有効期限が切れました — ステップ1からやり直してください
`canceled`	—	セッションがキャンセルされました — ステップ1からやり直してください

セッションのポーリング時に返される intent 固有の追加エラー：

HTTP	条件
`400`	SIGNUP — 生体認証 ID が既に登録されています（アカウントの重複）
`400`	SIGNIN — 生体認証 ID が登録されていません（アカウントが存在しません）

成功時のレスポンス：

{
  "result": {
    "sessionId": "b3f1a2c4-0000-0000-0000-abcdef012345",
    "status": "completed",
    "outcome": "matched",
    "authToken": "eyJhbGciOiJSUzI1NiJ9..."
  }
}

authToken を保存してください。以降のすべての Human Dashboard API リクエストで x-console-authorization ヘッダーとして使用します。

フェーズ1（代替） — メール OTP によるサインイン

ユーザーが既にアカウントを持ち、登録済みのメールアドレスに送信されるワンタイムコードでの認証を希望する場合は、生体認証の代わりにこのフローを使用します。メール OTP によるサインアップはサポートされていません — 初回登録には生体認証フローを使用してください。

ステップ1：OTP を送信する

curl -X POST https://api.humantoken.unico.app/api/console/v1/auth/email/sessions \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]"
  }'

メモ

メールアドレスは既存のアカウントに属している必要があります。アカウントが見つからない場合、ステップ2（OTP の検証）は 404 Not Found を返します。

レスポンス：

{
  "session": {
    "sessionId": "b3f1a2c4-0000-0000-0000-abcdef012345"
  }
}

sessionId を保存してください。指定したメールアドレスに6桁のコードが送信されます。

ステップ2：OTP を検証する

curl https://api.humantoken.unico.app/api/console/v1/auth/email/sessions/{sessionId}/{code}

HTTP	条件
`200`	コードが有効です — `authToken` が含まれます
`400`	コードが間違っています（`invalid otp code`）
`400`	OTP が使用済み、試行回数の上限に到達、または有効期限切れです
`404`	メールアドレスが登録されていません

成功時のレスポンス：

{
  "result": {
    "sessionId": "b3f1a2c4-0000-0000-0000-abcdef012345",
    "status": "completed",
    "outcome": "matched",
    "authToken": "eyJhbGciOiJSUzI1NiJ9..."
  }
}

authToken を保存してください。以降のすべての Human Dashboard API リクエストで x-console-authorization ヘッダーとして使用します。

フェーズ2 — 組織を設定する

ステップ3：組織を作成する

メモ

この呼び出しは一度だけ実行できます。テナントをプロビジョニングし、branchId を生成します。

どの国でも受け付けます。ISO 3166-1 alpha-3 の3文字コード（例：BRA、USA、MEX、DEU、IND）を使用してください。taxId はすべての国で任意です。

curl -X POST https://api.humantoken.unico.app/api/console/v1/organization \
  -H "x-console-authorization: <authToken>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Corp",
    "responsibleEmail": "[email protected]",
    "websiteUrl": "https://acme.com",
    "countryCode": "BRA",
    "logo": "https://acme.com/logo.png",
    "allowedDomains": ["https://app.acme.com"]
  }'

レスポンス：

{
  "organization": {
    "id": "e5d3f1a2-0000-0000-0000-abcdef012345",
    "name": "Acme Corp",
    "responsibleEmail": "[email protected]",
    "websiteUrl": "https://acme.com",
    "countryCode": "BRA",
    "tenantId": "tenant-acme-prod",
    "branchId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "taxId": "12345678000195"
  }
}

branchId を保存してください。デフォルトのブランチを識別し、ブランチとアクセスキーの管理に使用します。

ステップ4：アクセスキーを作成する

curl -X POST https://api.humantoken.unico.app/api/console/v1/access-keys \
  -H "x-console-authorization: <authToken>" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "production-key"
  }'

レスポンス：

{
  "accessKey": "uip_ak.prod.a1b2c3d4.e5f6g7h8.i9j0k1l2"
}

警告

accessKey は一度だけ返され、再度取得することはできません。 すぐにシークレットマネージャーに HUMAN_TOKEN_ACCESS_KEY として保存してください。

この値が、すべての Human Token API リクエストで使用される x-unico-accesskey ヘッダーです。

取得した値

値	使用する場所
`branchId`	デフォルトのブランチの識別、ブランチ固有のアクセスキーの作成
`accessKey`	すべての Human Token リクエストの `x-unico-accesskey` ヘッダー

組織の管理

組織を取得する

curl https://api.humantoken.unico.app/api/console/v1/organization/<organizationId> \
  -H "x-console-authorization: <authToken>"

レスポンス：

{
  "organization": {
    "id": "e5d3f1a2-0000-0000-0000-abcdef012345",
    "name": "Acme Corp",
    "responsibleEmail": "[email protected]",
    "websiteUrl": "https://acme.com",
    "countryCode": "BRA",
    "tenantId": "tenant-acme-prod",
    "branchId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "taxId": "12345678000195"
  }
}

組織を更新する

curl -X PUT https://api.humantoken.unico.app/api/console/v1/organization \
  -H "x-console-authorization: <authToken>" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "e5d3f1a2-0000-0000-0000-abcdef012345",
    "name": "Acme Corp",
    "responsibleEmail": "[email protected]",
    "websiteUrl": "https://acme.com",
    "countryCode": "BRA",
    "taxId": "12345678000195",
    "logo": "https://acme.com/logo-updated.png",
    "allowedDomains": ["https://app.acme.com", "https://checkout.acme.com"]
  }'

アクセスキーの管理

キーの一覧取得（メタデータのみ — シークレットは返されません）：

curl https://api.humantoken.unico.app/api/console/v1/access-keys \
  -H "x-console-authorization: <authToken>"

キーのローテーション（古いキーは即座に無効になります）：

curl -X POST https://api.humantoken.unico.app/api/console/v1/access-keys/rotate \
  -H "x-console-authorization: <authToken>" \
  -H "Content-Type: application/json" \
  -d '{"accessKey": "uip_ak.prod.a1b2c3d4.e5f6g7h8.i9j0k1l2"}'

キーの失効（元に戻せません）：

curl -X DELETE https://api.humantoken.unico.app/api/console/v1/access-keys \
  -H "x-console-authorization: <authToken>" \
  -H "Content-Type: application/json" \
  -d '{"accessKey": "uip_ak.prod.a1b2c3d4.e5f6g7h8.i9j0k1l2"}'

ブランチの管理

ブランチを使用すると、組織の設定（名前、ロゴ、許可するドメイン）をプロダクトや環境ごとに分けることができます。各ブランチは独自のアクセスキーを持つため、ブランチのコンテキストはリクエストで使用されたキーから自動的に解決されます。CreateProcess で branchId を渡す必要はありません。

ブランチを作成する

curl -X POST https://api.humantoken.unico.app/api/console/v1/organization/branches \
  -H "x-console-authorization: <authToken>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Mobile App",
    "logo": "https://acme.com/mobile-logo.png",
    "allowedDomains": ["https://mobile.acme.com"]
  }'

レスポンス：

{
  "branchId": "7ab1c2d3-0000-0000-0000-abcdef012345"
}

branchId を保存してください。ブランチ固有のアクセスキーを作成するときに使用します。

ブランチを更新する

curl -X PUT https://api.humantoken.unico.app/api/console/v1/organization/branches \
  -H "x-console-authorization: <authToken>" \
  -H "Content-Type: application/json" \
  -d '{
    "branchId": "7ab1c2d3-0000-0000-0000-abcdef012345",
    "name": "Mobile App v2",
    "logo": "https://acme.com/mobile-logo-v2.png",
    "allowedDomains": ["https://mobile.acme.com", "https://app.acme.com"]
  }'

ブランチ固有のアクセスキーを作成する

特定のブランチにスコープされたアクセスキーを生成するには、リクエストボディに branchId を含めます。

curl -X POST https://api.humantoken.unico.app/api/console/v1/access-keys \
  -H "x-console-authorization: <authToken>" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "mobile-app-key",
    "branchId": "7ab1c2d3-0000-0000-0000-abcdef012345"
  }'

レスポンス：

{
  "accessKey": "uip_ak.prod.z9y8x7w6.v5u4t3s2.r1q0p9o8"
}

警告

accessKey は一度だけ返されます。 すぐに保存してください。このキーで認証された CreateProcess リクエストは、キーに関連付けられたブランチの設定を自動的に使用します。

認証情報を設定する2つの方法​

ダッシュボードを使用する​

ベース URL​

認証方法​

生体認証ログインの intent​

フェーズ1 — 認証​

ステップ1：生体認証ログインセッションを開始する​

ステップ2：セッションが解決されるまでポーリングする​

フェーズ1（代替） — メール OTP によるサインイン​

ステップ1：OTP を送信する​

ステップ2：OTP を検証する​

フェーズ2 — 組織を設定する​

ステップ3：組織を作成する​

ステップ4：アクセスキーを作成する​

取得した値​

組織の管理​

組織を取得する​

組織を更新する​

アクセスキーの管理​

ブランチの管理​

ブランチを作成する​

ブランチを更新する​

ブランチ固有のアクセスキーを作成する​

認証情報を設定する2つの方法

ダッシュボードを使用する

ベース URL

認証方法

生体認証ログインの intent

フェーズ1 — 認証

ステップ1：生体認証ログインセッションを開始する

ステップ2：セッションが解決されるまでポーリングする

フェーズ1（代替） — メール OTP によるサインイン

ステップ1：OTP を送信する

ステップ2：OTP を検証する

フェーズ2 — 組織を設定する

ステップ3：組織を作成する

ステップ4：アクセスキーを作成する

取得した値

組織の管理

組織を取得する

組織を更新する

アクセスキーの管理

ブランチの管理

ブランチを作成する

ブランチを更新する

ブランチ固有のアクセスキーを作成する