ガイド本文は英語です。サイトのナビゲーションは選択した言語のままです。
← ドキュメントAPI リファレンス
各エンドポイントは OpenAPI 仕様から生成されます — このページがクライアントの契約からずれないように。仕様をダウンロードしてクライアントを生成するか Postman にインポートしてください。
ベース URL
https://sandbox.identityinc.io- Sandbox — free test verifications (real Shufti test account), simulated chain. Keys are bi_test_… and must not be sent to production. Mint via POST /v1/billing/checkout on this host (see Quickstart).
https://api.identityinc.io- Production — the base URL for the API key issued at signup (bi_…)
公開 とマークされていない限り、すべてのエンドポイントは Authorization: Bearer <key> を使います。認証 を参照。
Accounts
POST/v1/accounts/freeSponsor free provisional account
リクエストボディ
ownerPublicKey必須 | string | |
activePublicKey | string | |
passkeyCredentialId | string | |
preferredName | string | Requested account name. Permanent once created. Conflicts with an existing name return 409 and hand the kycCreateToken back, so the caller can retry with a different name without repeating KYC. Pattern: ^[a-z1-5.]{1,12}$ |
deviceFingerprint | string | |
personDid | string | |
kycCreateToken | string | One-time token from GET /v1/kyc/status after approval. |
emailProofToken | string | From POST /v1/email/otp/confirm. Binds the verified address to the new account. Required when the organization sets requireEmailProofBeforeFreeCreate. |
phoneProofToken | string | From POST /v1/phone/otp/confirm. |
レスポンス
201 | Created |
409 | Requested name, email, or number already taken |
GET/v1/accounts/name-availableCheck whether an account name can be claimed
Advisory only. Nothing is reserved: the chain is the authority and /v1/accounts/free re-checks, so a name can still be lost between this call and create.
パラメータ
name必須 | string · クエリ |
レスポンス
200 | Availabilityname: string · available: boolean · reason: TAKEN | INVALID · message: string |
POST/v1/accounts/unlockRemove faucet cosigner after bind
レスポンス
200 | Unlocked |
GET/v1/accounts/{did}Account status, lifecycle, and active bindings
パラメータ
did必須 | string · パス | Account DID, URL-encoded (`did:antelope:<chain>:<name>`) |
レスポンス
200 | Account with non-revoked bindings |
404 | Account not found in this organization |
KYC
POST/v1/kyc/startStart KYC; returns verification URL / access token
Person-first by default: omit `accountDid` to create a Person before any chain account (required when the organization gates free-create on KYC). Identity checks are document + face via Shufti Pro — BoundIdentity does not enable Shufti phone OTP for KYC. On sandbox, complete `verificationUrl` with a Shufti test ID (free on the test account).
リクエストボディ
accountDid | string | Optional. Omit for person-first KYC before free-create. |
levelName | string | |
redirectUrl | string | Optional post-Shufti browser return. Sandbox allows only jungle4.blocksfinity.com /identity paths. Live allows only blocksfinity.com /identity paths. Invalid values are ignored. |
レスポンス
200 | Token issued |
429 | KYC-start budget spent for this organization or IP |
502 | `PROVIDER_FAILURE` — the provider rejected the request (bad level name, credentials, or plan). Not transient: the same request gets the same answer, so fix it rather than retrying. |
503 | `PROVIDER_UNAVAILABLE` — every configured provider was unreachable or erroring. Already retried, and failed over to a standby where one is configured, before you saw this. Safe to retry with backoff; `details.retryAfterSec` is present when the provider named a window. |
GET/v1/kyc/statusKYC status for a person
パラメータ
personDid必須 | string · クエリ | |
refresh | 1 | true · クエリ | When the person is not already approved, pull the current review from the KYC provider. Use after a missed webhook or a hosted session that later succeeded. Do not send this on every poll. |
レスポンス
200 | Status, level, provider, and country. Approved people also receive a one-time create token. |
404 | Person not found in this organization |
KYB
POST/v1/kyb/startStart Know-Your-Business for a legal entity
レスポンス
200 | Organization pending |
502 | `PROVIDER_FAILURE` — the provider rejected the request; not transient |
503 | `PROVIDER_UNAVAILABLE` — every configured provider was unreachable. Retry with backoff; see `/v1/kyc/start` for the full contract. |
Bind
POST/v1/bind/challengeIssue bind nonce for wallet signature
レスポンス
200 | Challenge |
POST/v1/bind/confirmConfirm bind with signature; issue AccountBinding VC
レスポンス
200 | Bound |
Compliance
POST/v1/aml/screen-applicantScreen applicant id hash (sanctions / denylist)
レスポンス
200 | Screen result |
POST/v1/risk/assessAnti-abuse risk score before free create / bind
レスポンス
200 | Assessment |
POST/v1/compliance/exportExport hash-chained audit log for a date range
レスポンス
200 | Export job |
GET/v1/compliance/exportsList recent compliance export jobs
レスポンス
200 | Jobs |
GET/v1/compliance/export/{jobId}Fetch completed export artifact
パラメータ
jobId必須 | string · パス |
レスポンス
200 | Job + artifact JSON |
POST/v1/compliance/audit/verifyVerify audit hash-chain integrity
レスポンス
200 | Verification result |
Admin
POST/v1/admin/accounts/suspendSuspend an account (compliance action)
レスポンス
200 | Suspended |
GET/v1/admin/dashboardOrganization dashboard aggregates (lifecycle, AML, recent audit)
レスポンス
200 | Dashboard payload |
GET/v1/admin/accountsList chain accounts for the organization
レスポンス
200 | Account list |
GET/v1/admin/peopleList people / KYC subjects
レスポンス
200 | People list |
GET/v1/admin/organizationsList KYB businesses
レスポンス
200 | Businesses |
GET/v1/admin/auditHash-chained audit log entries
レスポンス
200 | Audit entries |
GET/v1/admin/membersOrganization console memberships (requires admin scope)
レスポンス
200 | Members |
POST/v1/admin/membersAdd a console member, or restore and re-role a revoked one
The membership roster decides who may sign in to the admin console and what they may do there. Roles, weakest first: `viewer`, `operator`, `compliance_officer`, `admin`, `owner`. Re-adding an existing address updates its role and reactivates it, so a returning colleague does not collide with their old row. While an organization has no members at all, the console accepts any address with the correct password and treats it as an `owner` — adding the first member closes that path.
リクエストボディ
email必須 | string (email) | |
role必須 | viewer | operator | compliance_officer | admin | owner |
レスポンス
201 | Member added or updated |
PATCH/v1/admin/members/{email}Change a member's role or reactivate them
パラメータ
email必須 | string (email) · パス |
リクエストボディ
role | viewer | operator | compliance_officer | admin | owner | |
active | boolean |
レスポンス
200 | Updated |
404 | No such member in this organization |
DELETE/v1/admin/members/{email}Revoke a member's console access
Deactivates rather than deletes. The address remains the recorded actor on every audit entry the member produced, and removing the row that explains who they were would leave those entries unresolvable.
パラメータ
email必須 | string (email) · パス |
レスポンス
200 | Revoked |
404 | No such member in this organization |
GET/v1/admin/amlPEP / sanctions alerts + AML audit events
レスポンス
200 | Screening feed |
GET/v1/admin/riskAnti-abuse posture (velocity, shared devices, risk events)
レスポンス
200 | Risk summary |
GET/v1/admin/tenantCurrent organization + policy (scoped by API key)
レスポンス
200 | Organization detail |
GET/v1/admin/api-keysList API keys (prefixes only)
レスポンス
200 | Keys |
POST/v1/admin/api-keysCreate or rotate API key (raw returned once)
リクエストボディ
name必須 | string | Max length 64. |
revokeKeyId | string (uuid) | Deactivate this key after minting the new one |
scopes | read | accounts_write | kyc_write | bind_write | unlock_write | admin | compliance_export | webhook_manage[] | Least-privilege scope set. **Omitting this grants every scope, including `admin`** — the historical behaviour of this endpoint. Pass a narrower set for a key that only needs part of the API, for example `["read"]` for a dashboard or `["accounts_write","kyc_write"]` for an onboarding service. |
レスポンス
201 | Created — the raw key is returned once and never againid: string (uuid) · prefix: string · apiKey: string · scopes: string[] · revokedKeyId: string · warning: string · scopeNotice: string |
DELETE/v1/admin/api-keys/{id}Revoke API key
パラメータ
id必須 | string · パス |
レスポンス
200 | Revoked |
POST/v1/admin/signing/enableEnable HMAC request signing (secret once)
レスポンス
200 | HMAC secret |
POST/v1/admin/signing/disableDisable HMAC request signing
レスポンス
200 | Disabled |
PUT/v1/admin/ip-allowlistReplace organization IP allowlist
レスポンス
200 | Allowlist |
POST/v1/admin/dpa/acceptAccept Data Processing Agreement (sets dpaAcceptedAt)
レスポンス
200 | Acceptance recorded |
GET/v1/admin/webhooksList outbound webhooks
レスポンス
200 | Webhooks |
POST/v1/admin/webhooksRegister outbound webhook (signing secret once)
レスポンス
201 | Registered |
DELETE/v1/admin/webhooks/{id}Deactivate outbound webhook
パラメータ
id必須 | string · パス |
レスポンス
200 | Deactivated |
GET/v1/admin/webhooks/deliveriesRecent outbound delivery attempts
Diagnostics for a receiver that is rejecting events: status, attempt count, and the last error per delivery. Scoped to your own webhooks.
パラメータ
status | pending | failed | delivered | dead · クエリ | |
limit | integer · クエリ |
レスポンス
200 | Delivery attempts |
POST/v1/admin/webhooks/deliveries/{id}/replayResend a delivery that gave up
Re-queues a `failed` or `dead` delivery and resets its attempt counter, for use once the receiving system has been repaired. The signed body is stored with the delivery, so the replay carries the original payload and signature inputs rather than a regenerated approximation. Deliveries that already succeeded are refused — deduplicate on `X-BI-Delivery-Id` if you need to reprocess one.
パラメータ
id必須 | string · パス |
レスポンス
200 | Re-queued |
409 | Already delivered, or the payload is no longer available |
GET/v1/tenantCurrent organization posture (signing, allowlist, policy)
レスポンス
200 | Organization |
PUT/v1/admin/country-policySet the organization's jurisdiction policy
Enforced when binding a person to an account: a country on `blockedCountries`, or absent from a non-empty `allowedCountries`, is refused. The blocklist takes precedence. When either list is non-empty a subject whose country is unknown is also refused, so the control cannot be bypassed by an unresolvable jurisdiction. Empty lists mean no restriction. Omit a field to leave it unchanged.
リクエストボディ
allowedCountries | string[] | ISO-3166 alpha-2 codes |
blockedCountries | string[] |
レスポンス
200 | Policy appliedallowedCountries: string[] · blockedCountries: string[] |
400 | A code was not a valid alpha-2 |
AML
POST/v1/aml/screen-accountKYT-style screen of a chain account
リクエストボディ
chainAccount必須 | string |
レスポンス
200 | Score and labels |
POST/v1/aml/clearClear PEP / sanctions flags on a person
Compliance-officer action. Requires `compliance_export`. By default this resets `pepFlag`, `sanctionsFlag`, and `riskScore` immediately, closes any open AML case for the subject as `cleared`, and writes an `aml.cleared` audit entry with the reason. When the organization's policy sets `requireSecondApprovalToClearAml` (four eyes), this call only *proposes* the clear: the case moves to `pending_approval`, the flags stay up, and the response carries `pendingApproval: true` with the `caseId`. A different person then calls `/v1/aml/cases/{caseId}/approve-clear`, which is what lifts the flags. If the subject has no open case, one is opened by hand so the proposal has somewhere to live.
リクエストボディ
subjectDid必須 | string | |
reason必須 | string | Max length 500. |
レスポンス
200 | Flags cleared, or (under four eyes) a clear proposed.cleared: boolean · pendingApproval: boolean · caseId: string · subjectDid: string |
404 | Person not found in this organization |
409 | The case was closed by someone else while this decision was being made |
GET/v1/aml/casesThe open AML case queue, worst first
Cases with status `open` or `pending_approval`, ordered by priority (set from match severity) then age. Requires `compliance_export`.
レスポンス
200 | List of cases |
POST/v1/aml/cases/{caseId}/approve-clearApprove a proposed clear (four eyes)
The second pair of eyes. Lifts the subject's flags and closes the case as `cleared`, in one transaction. Refused when the approver is the identity that proposed it: a tenant-minted API key counts as one person, and the console derives the operator from the signed session. Requires `compliance_export`.
パラメータ
caseId必須 | string · パス |
リクエストボディ
notes | string | Max length 500. |
レスポンス
200 | Flags cleared and case closed |
403 | The person who proposed the clear cannot approve it |
404 | Case not found in this organization |
409 | Case is not awaiting approval |
POST/v1/aml/cases/{caseId}/confirmConfirm the match and close the case
One person may always make things stricter. Closes the case as `confirmed`; the flags stay up. Requires `compliance_export`.
パラメータ
caseId必須 | string · パス |
リクエストボディ
reason必須 | string | Max length 500. |
レスポンス
200 | Case confirmed |
404 | Case not found in this organization |
409 | Case already closed |
Billing
POST/v1/billing/chain/confirm公開Settle an on-chain A payment for a Growth checkout
Verifies a transfer to the treasury carrying this checkout's memo, then provisions the organization. A transaction id can only ever pay for one checkout. Returns 425 while the transfer is still reversible — retry shortly rather than treating it as a rejection.
リクエストボディ
sessionId必須 | string | |
transactionId必須 | string | |
account | string | Optional payer; when set the transfer must originate from it |
レスポンス
201 | Organization set up (API key returned once) |
400 | Payment not verified |
409 | Already provisioned |
425 | Transfer seen but not yet irreversible — retry |
GET/v1/billing/checkout/{sessionId}公開Poll checkout status
パラメータ
sessionId必須 | string · パス |
レスポンス
200 | Status with a masked email; never includes the API key |
404 | Unknown session |
Phone
POST/v1/phone/otp/startSend an SMS one-time code
Rate limited per phone and per client IP. Requires `accounts_write`. On hosted sandbox and production the code is delivered by SMS only — it is never returned in the response body.
リクエストボディ
phone必須 | string | E.164, or a local Ghana number |
レスポンス
200 | Challenge issuedchallengeId: string (uuid) · expiresAt: string (date-time) · phoneMasked: string |
429 | Too many codes for this phone or IP |
POST/v1/phone/otp/confirmConfirm an SMS code, returning a short-lived phone proof
Capped at 5 attempts per challenge. The returned `phoneProofToken` is accepted by `POST /v1/accounts/free` for 4 hours.
リクエストボディ
challengeId必須 | string (uuid) | |
code必須 | string |
レスポンス
200 | Proof issuedphoneProofToken: string · expiresInSec: integer · personDid: string · softIdentity: boolean |
400 | Invalid or expired code |
429 | Attempt cap reached for this challenge |
Contact
Verified email and phone bound to an account. Contact channels are never identity evidence - KYC owns that.
POST/v1/email/otp/startEmail a verification code
Confirming an email never creates or promotes a Person. Email is a contact channel; KYC remains the only identity authority.
リクエストボディ
email必須 | string (email) |
レスポンス
200 | Challenge issuedchallengeId: string (uuid) · expiresAt: string (date-time) · emailMasked: string · devCode: string |
409 | Address already bound to an account |
POST/v1/email/otp/confirmConfirm an emailed code; returns a short-lived emailProofToken
リクエストボディ
challengeId必須 | string (uuid) | |
code必須 | string |
レスポンス
200 | VerifiedemailProofToken: string · expiresInSec: integer · emailMasked: string |
429 | Too many attempts on this challenge |
GET/v1/accounts/{did}/contactMasked view of the contacts bound to an account
パラメータ
did必須 | string · パス | Account DID, or the bare chain name. |
レスポンス
200 | Masked contacts; raw values are never returned |
POST/v1/accounts/contact/challengeIssue a nonce the account's owner key must sign to change a contact
Contact changes are authorized by the account key, not by the session — whoever can change the address controls where account notices go. The nonce is single-use and consumed by the matching start call.
リクエストボディ
accountDid必須 | string | |
channel必須 | email | phone |
レスポンス
200 | Challengenonce: string · payloadToSign: string · expiresAt: string (date-time) |
POST/v1/accounts/contact/email/startSend a code to a proposed new email
Nothing is unbound until the code is confirmed.
リクエストボディ
accountDid必須 | string | |
email必須 | string (email) | |
nonce必須 | string | |
signature必須 | string |
レスポンス
200 | Challenge issued |
400 | INVALID_SIGNATURE - the signature does not verify against the account's active key. |
409 | Address already bound to another account |
POST/v1/accounts/contact/email/confirmConfirm the code and swap the bound email
Detach and attach run in one transaction, so the account is never left without a verified email. The previous address is notified.
リクエストボディ
challengeId必須 | string (uuid) | |
code必須 | string |
レスポンス
200 | Changed |
POST/v1/accounts/contact/phone/startSend a code to a proposed new phone number
リクエストボディ
accountDid必須 | string | |
phone必須 | string | |
nonce必須 | string | |
signature必須 | string |
レスポンス
200 | Challenge issued |
POST/v1/accounts/contact/phone/confirmConfirm the code and swap the bound phone number
リクエストボディ
challengeId必須 | string (uuid) | |
code必須 | string |
レスポンス
200 | Changed |
Resolution
GET/.well-known/did.json公開Issuer DID document (W3C did:web)
Publishes the Ed25519 `assertionMethod` key used to sign issued credentials. A relying party needs only this document to verify a credential offline.
レスポンス
200 | DID document |
GET/people/{personId}/did.json公開Person DID document (W3C did:web)
パラメータ
personId必須 | string (uuid) · パス |
レスポンス
200 | DID document exposing KYC status only |
404 | Unknown person |
GET/orgs/{orgId}/did.json公開Organization DID document (W3C did:web)
パラメータ
orgId必須 | string (uuid) · パス |
レスポンス
200 | DID document exposing KYB status only |
404 | Unknown organization |
Ops
GET/v1/health公開Liveness
レスポンス
200 | OK |
GET/v1/whoami公開The source IP this API attributes to you
Returns the address tenant IP allowlists are compared against. Call it from the server that will hold your API key before configuring an allowlist: NAT and egress gateways mean the address we see is often not the one you expect, and an allowlist that does not match fails closed — every request returns 403. Unauthenticated, and returns nothing beyond your own address.
レスポンス
200 | The caller's resolved source addressclientIp: string |
GET/v1/ready公開Readiness
レスポンス
200 | Ready |
503 | Not ready |
GET/v1/metricsMetrics (Prometheus text exposition)
Requires `read` scope.
レスポンス
200 | text/plain exposition |
401 | Missing or invalid API key |
GET/v1/billing/plans公開Public Identity Inc. plan catalog
レスポンス
200 | Plans |
POST/v1/billing/ai/advise公開AI checkout advisor (rate-limited)
レスポンス
200 | Recommendation |
429 | Rate limited |
POST/v1/billing/email/otp/start公開Send a signup verification code to the claimed work email
Required before POST /v1/billing/checkout. Proves control of the mailbox that will own the organization. Unauthenticated. Rate-limited per IP and per address. In non-production mock mode the response may include `devCode`; production never echoes the code.
レスポンス
200 | Challenge id and masked email |
429 | Rate limited |
POST/v1/billing/email/otp/confirm公開Confirm the signup email code and receive a one-time proof token
Spend the emailed code. The returned `emailProofToken` is accepted once by POST /v1/billing/checkout for the same address.
レスポンス
200 | emailProofToken |
400 | Incorrect or expired code |
POST/v1/billing/checkout公開Builder signup, Growth Stripe Checkout, or Institutional lead
Requires `emailProofToken` from POST /v1/billing/email/otp/confirm. Builder mints a full-access API key only after that proof is spent.
レスポンス
200 | Redirect or sales lead |
201 | Builder provisioned |
403 | Email not verified |
429 | Rate limited |
POST/v1/billing/stripe/webhook公開Stripe lifecycle + checkout.session.completed
レスポンス
200 | Received |
POST/v1/billing/checkout/complete公開Complete a pending Growth checkout (sandbox / test settlement)
レスポンス
200 | Provisioned or upgraded |
POST/v1/billing/checkout/reveal公開Reveal API key once after Stripe Checkout (rate-limited)
レスポンス
200 | Key payload |
GET/v1/billing/usagePlan + usage meters for the authenticated organization
レスポンス
200 | Usage snapshot |
POST/v1/billing/upgradeBuilder → Growth Checkout (keeps organization + keys)
レスポンス
200 | Checkout redirect |
POST/v1/billing/portalStripe Customer Portal session
レスポンス
200 | Portal URL |