System Users & API Keys
System users are the people who sign in to your tenant — administrators, support staff,
auditors. They are a different population from subjects, the people being verified. This
page covers how system users and long-lived API tokens are managed, and what the rest of the
admin console at https://acme.identiwise.com/admin/ does.
Auth: a system bearer token. Most operations here require the superuser role; the router
checks the role before the handler runs. See Authentication.
1. System users
List users
GET /api/v1/admin/users — optional role and status filters.
curl "https://acme.identiwise.com/api/v1/admin/users?role=admin" \
-H "Authorization: Bearer YOUR_SUPERUSER_TOKEN"
Create a user
POST /api/v1/admin/users — username, email and password are required. role is optional
and one of admin, superuser or view; it defaults to admin when omitted, so send it
explicitly unless you mean to create an administrator.
{
"username": "jdoe",
"email": "jdoe@example.com",
"password": "a-strong-passphrase",
"role": "admin"
}
The password must satisfy the platform password policy — the same policy applied at
registration, at team-add in the account portal and at self-service change. No e-mail is
sent: nothing in the platform sends mail, so pass the initial credential to the person
yourself. A duplicate e-mail is answered 409.
Read, update, delete
GET /api/v1/admin/users/{id}PATCH /api/v1/admin/users/{id}—username,email,role,statusDELETE /api/v1/admin/users/{id}
curl -X PATCH "https://acme.identiwise.com/api/v1/admin/users/55" \
-H "Authorization: Bearer YOUR_SUPERUSER_TOKEN" \
-H "Content-Type: application/json" \
-d '{"status":"suspended"}'
Suspending, deleting or demoting a user takes effect on that user's next request — a live session is re-checked against the user's row every time, not only at login. Role changes, suspensions and deletions are written to the audit trail.
System user ids are integers. Subject, submission, token, preset and workflow ids are UUID strings.
2. API tokens
Long-lived bearer tokens let your backend call Identiwise without an interactive login. They are stored hashed and the plaintext is shown once, at creation.
Only a superuser may create or revoke API tokens, in the API and in the account portal alike.
A token carries the powers of the tenant it belongs to — keep it in your server's secret store,
never in a browser or a mobile app. For the browser, mint a short-lived
ephemeral token instead.
Create
POST /api/v1/admin/api-tokens
| Field | Type | Description |
|---|---|---|
description | string | A label, e.g. Production backend. Max 255 characters. |
expires_at | string | YYYY-MM-DD, YYYY-MM-DD HH:MM:SS or RFC 3339 …T…Z. Absent or empty means no expiry. |
curl -X POST "https://acme.identiwise.com/api/v1/admin/api-tokens" \
-H "Authorization: Bearer YOUR_SUPERUSER_TOKEN" \
-H "Content-Type: application/json" \
-d '{"description":"Production backend","expires_at":"2027-12-31"}'
The response carries the token once. Store it immediately; it cannot be retrieved again.
List and revoke
GET /api/v1/admin/api-tokens returns the tenant's tokens — id, owning user, description,
expiry and creation time, never the secret itself. DELETE /api/v1/admin/api-tokens/{id}
revokes one, effective on the next request that presents it. Creation and revocation are both audited.
3. The admin console
The console is a static single-page app served from your tenant host at /admin/. It holds the
bearer token in memory for the session only — never in browser storage — and it calls the same
public API documented here, so anything it does you can do from your own code.
| Module | What it does |
|---|---|
| Users | The /admin/users routes above: list, create, edit role and status, delete. |
| API keys | Mint, list and revoke long-lived tokens. Superusers only. |
| Subjects | Search by internal id, your own external UID, name or e-mail; create and edit subjects; open a read-only history of every licence and selfie attempt for one subject. |
| Workflow builder | Define an ordered list of verification steps — verify_license, check_selfie, age_gender_estimation and manual_review_trigger — that the hosted verify UI renders as a wizard. "Copy JSON" gives you the payload to create the same workflow through the API. |
| Token presets | Reusable templates for ephemeral tokens: capability flags, attempt caps, min_age, an attached workflow, time-to-live. Each preset can export a ready-to-paste cURL, PHP or Python snippet that mints a token from it. |
| Review queue | Submissions parked for a human. Each card shows the stored image, the OCR score, the reason the pipeline parked it, and the AI metadata recorded for that submission. Approve, or reject with a note and optionally a re-upload request. |
| Privacy queue | Outstanding erasure requests — see below. |
| Submissions | A combined, date-filtered list of licence and selfie submissions with their review state. |
| Raw data | The superuser-only table export, JSON or CSV. See Reporting. |
| Usage | Request counts for the tenant over a date range. See Reporting. |
| Ephemeral token tool | Mint a short-lived subject token by hand (optionally from a preset). The console displays the token and its expiry for you to paste into /verify/?token=… yourself, so you can try the subject journey without writing backend code. |
The builder offers per-step configuration fields alongside each step. Those values are stored
with the workflow and echoed back, but nothing in the verification pipeline reads them —
they change nothing about how a submission is judged. One is read for display only: the
manual_review_trigger step's reason is shown to the subject as that step's description.
Enforcement is planned; until it ships, treat the per-step fields as notes to yourself.
The manual_review_trigger step itself is a stop panel in the hosted UI: it tells the subject
the session needs a human and ends the wizard. It does not by itself change a submission's
review state.
AI metadata on a review card
For a licence, the card shows the OCR score, and — when the document carried a second, "ghost"
portrait — the internal face match between the two faces on the document. When a submission
was run through ?type=analyze, the estimated age returned by the model is recorded against
the submission as an admin note ([AI Analysis] Age: 25) and shown with the review. Gender and
emotion are not inferred and are not recorded. An estimated age is a model output shown to help
a human decide; it is not a verdict on its own.
Privacy queue
Erasure requests — raised by a subject through their own credential, or by an administrator on the subject's behalf — appear as a queue of subjects with an outstanding request. Approving one runs the full erasure: the stored images and the database rows go in a single transaction, and the completed erasure is written to the audit trail. There is one pending request per subject; a repeat request returns the outstanding one rather than adding another.