Platform Overview
Identiwise is a multi-tenant, AI-assisted identity verification service for online businesses. A customer (a tenant) sends us a person to verify (a subject), the subject submits an identity document and a selfie, and Identiwise runs document detection, face detection and matching, OCR and age estimation — returning a decision in the HTTP response or parking the submission for a human reviewer.
Identiwise is in final development. No API tokens are being issued yet and no account can be opened. This documentation describes the API as it will ship, and is published so that you can evaluate the integration ahead of launch. To be told when access opens, email hello@identiwise.com.
Start here
This page is the reference for how the platform fits together. If you would rather follow the integration in order, these are the three steps that get an image through the pipeline:
| Step | Page | What you do |
|---|---|---|
| 1. Get a credential | Authentication | Sign in as a staff user, or use a long-lived bearer token from your backend |
| 2. Mint a token for one subject | Ephemeral tokens | Create a short-lived, capability-scoped token for the person you are verifying |
| 3. Submit an image | Client actions | Send the document or selfie with that token and read the verdict from the response |
What you get
Every tenant is served on its own hostname, {tenant}.identiwise.com, which carries three
surfaces:
| Surface | Path | Who uses it |
|---|---|---|
| REST API | /api/v1 | Your backend — subjects, tokens, submissions, review, exports |
| Admin console | /admin/ | Your staff — review queue, subjects, submissions, users, tokens |
| Hosted verification UI | /verify/?token=… | The subject — mobile-friendly camera capture, details form, messages, re-upload, and a QR hand-off from desktop to phone |
A separate account portal handles sign-up, plan, team and security settings (two-factor enrolment, the IP allow-list). It is not public yet.
You do not have to use the hosted UI. It is one client of the same public API, so you can
build your own capture flow against /api/v1 and the ephemeral-token endpoints instead.
Architecture
Identiwise runs on IONOS Cloud in Frankfurt, Germany. All processing and storage stay in the EU.
Data is split across two layers:
- The lookup database (central). Tenants, their hostnames, staff accounts, API tokens,
plans and per-tenant configuration. It is also the routing table: the tenant is resolved
from the request's
Hostheader before anything else runs, soacme.identiwise.comandglobex.identiwise.comreach different data on the same code. - The tenant shards (isolated). Subjects, their details, submissions, tokens, workflows,
messages, erasure requests and usage records. Each tenant is assigned to one shard, and
every row on it carries a
tenant_id.
Being on the right shard is not treated as sufficient on its own. Every query against a tenant-owned table carries an explicit tenant predicate, and a static lint in our CI pipeline fails the build if one does not — with no baseline file of grandfathered exceptions to hide in. A cross-tenant isolation suite drives that boundary from the outside on every commit, including between two tenants that share a shard, where the SQL predicate is the only separation.
Identifiers on the shard side — subjects, submissions, tokens, presets, workflows — are UUID strings. Staff users and long-lived API tokens use integer ids.
The verification pipeline
The pipeline runs synchronously: the subject's upload request stays open until the pipeline finishes, and the verdict comes back in that response. Each run is wall-clock budgeted (150 seconds by default); a run that exhausts its budget parks the submission for review rather than guessing.
1. Document detection
A custom-trained document-detection model checks that the image actually contains an identity document.
Today that model is trained on US (Texas) driver's licences. Passports and national ID cards (MRZ), US and Canadian licence barcodes (PDF417), and UK, EU and Australian documents are on the roadmap — they are not supported yet.
2. Face detection and internal consistency
A facial-recognition model locates the faces on the document. The largest is the primary portrait; a secondary face — the "ghost photo" printed on many licences — is compared against the primary one, and a mismatch flags the document for a human.
3. Reference matching
The document's face is compared against the subject's approved reference selfie (or, on a selfie submission, against the approved document photo). The match decision is the face-matching engine's own verified / not-verified result — there is no similarity number for you to tune.
If the reference cannot be retrieved, has no detectable face, or the comparison service is unavailable, the submission is parked for review with that reason. An infrastructure failure is never reported as a verdict about the person.
4. OCR against the subject's details
An OCR engine reads the document, and the extracted text is scored against the details the subject provided — name, date of birth, licence number, street. Date formats are matched region-agnostically rather than assuming one ordering.
5. Age estimation
POST /subject/upload?type=verify_age checks the estimated age against the token's min_age
and returns age_verified. ?type=analyze returns the estimated age only, without an
age gate.
Identiwise does not perform emotion recognition or gender inference. Both were deliberately removed from the product, and neither is requested from the model or returned by the API.
Outcomes
| Outcome | What it means |
|---|---|
| Approved | e.g. LICENSE_APPROVED, SELFIE_APPROVED — the checks passed |
| Pending admin review | e.g. LICENSE_PENDING_APPROVAL with a stated reason — the submission is undecided and waiting for a human, not rejected |
| Not matched / no face | ID_NOT_MATCHED, NO_FACE_DETECTED — a verdict about the images themselves |
Administrators work the queue from the admin console: approve, reject, request a re-upload,
and exchange messages with the subject. Identiwise does not push results anywhere: the verdict
is in the upload response, and any later change of state is read back from
GET /admin/review or GET /admin/submissions.
Two assurance flows
Each ephemeral token selects how strictly a licence may be approved:
- Document check (default). A licence for a subject with no approved reference selfie may
be approved on document detection and OCR alone. The approval says so:
face_comparison: "none". It asserts that the document reads correctly — not that the presenter's identity was established. - Strict (
require_face_match: true). A licence approval requires a face comparison against an approved reference. With no reference on file the submission parks for admin review — OCR still runs, so the reviewer has the score as evidence — and one admin approval anchors the subject, after which automation resumes. A successful comparison recordsface_comparison: "matched".
Security model
Two token types, with deliberately different reach:
| Token type | Header | Principal | Scope | Lifespan |
|---|---|---|---|---|
| Bearer token | Authorization: Bearer <token> | Staff user or server integration | The whole tenant, gated by role (superuser / admin / view) | Long-lived; optional expires_at; revocable at any time |
| Ephemeral token | X-Api-Key: <token> | One subject, in their own browser or app | That one subject, limited to the capabilities enabled at mint | expires_in_minutes (default 60), and an optional max_uses — an exhausted token is fully dead |
Your backend holds the bearer token and mints an ephemeral token per subject. The subject's device only ever holds the ephemeral one, so a leaked client-side token exposes a single subject for minutes, not your tenant. With the hosted UI — or your own UI served from the tenant host — uploads go straight from the subject's device to Identiwise and you never proxy the image bytes. See Web integration for the one case where a backend proxy is required today.
Bearer tokens are never stored in readable form: we keep a SHA-256 fingerprint to find the row and a bcrypt hash to verify it, so a stolen database row cannot be replayed as a credential. Ephemeral tokens are minutes-long, single-subject credentials and are not long-term secrets — treat one as valid until it expires or its uses run out, and mint a fresh one per subject rather than reusing it.
See Authentication for the full flow.
Access controls
TLS on every hostname · three roles with authorisation enforced in the router · TOTP two-factor authentication with recovery codes, and tenant-wide 2FA enforcement · per-user 2FA lockout (5 failures / 15 minutes) · per-IP login rate limiting (20 failures / 15 minutes) · a per-tenant IPv4/CIDR allow-list · a password policy on every human-chosen password, and a password change that evicts the user's other portal sessions and cancels any outstanding login challenge (an admin-console sign-in holds an API token rather than a portal session, and is revoked only if the user opts in at the same time) · an append-only audit log covering document views, raw exports, review decisions, erasures, logins, authorisation refusals, 2FA changes, token issuance, role and staff changes, password changes, subject record changes and erasure requests.
Image storage
Identity documents and selfies are written to a private, S3-compatible object store, in the same Frankfurt region as the databases. Files are never served publicly and the bucket has no anonymous access.
To display an image, an administrator calls GET /admin/photos/{type}/{id}, which records
the access in the audit log first and then redirects to a 15-minute pre-signed URL.
If the access cannot be recorded, no URL is issued. GET /admin/submissions deliberately
does not return the stored object key — it reports only whether a file exists (has_file) —
and GET /admin/photos/{type}/{id} is the audited route that issues access to the image
itself.
Erasure requests — raised by an administrator, or by the subject's own credential through
POST /api/v1/subject/request-deletion (the hosted UI does not render a control for this
today, so surface one from your own page if you need to offer it) — delete the stored images
and the database rows together. Automated retention purging is on
the roadmap and is not live today; data is kept until it is erased on request or by you.
Identiwise acts as a processor; you remain the controller. The Privacy Policy on the main site sets out the detail.