Biometric Step-Up for AI API Access: Binding Privilege to a Person

Verification at onboarding proves who created an account. It proves nothing about who is using it now.

That gap is ordinary in most products and consequential on an AI platform, where the assets behind the account are model access, credits and quota. An API key is a bearer token — whoever holds it is the account. Keys get shared inside teams, pasted into repositories, sold on, and taken over. Six months after a clean onboarding, "this account was verified" is a statement about the past.

Biometric authentication closes that gap. It re-verifies the actual human at the moment of a privileged action — no documents, no password, under two seconds, $0.10 per authentication.

Key takeaways

• Onboarding verification is a snapshot. Biometric authentication is a check at the moment it matters.
• Liveness plus face match against the portrait already stored from the user's original verification. No documents, no password.
• Session-only. There is no /v3/biometric-auth/ endpoint — it runs through a session with workflow_type=BIOMETRIC_AUTHENTICATION.
• The critical implementation detail: use the same vendor_data as the user's original verification, or the stored face cannot be retrieved.
• Right triggers: quota increases, credit grants, new API key issuance, tier upgrades, adding privileged team members, and any behavioral alert from your traffic layer.
• $0.10 per authentication, pay-per-success, sub-two-second.

Why re-authentication belongs on an AI platform

Three failure modes make the onboarding snapshot insufficient.

Key sharing and resale. A key issued to a verified developer can end up anywhere. The account stays verified; the person using it is not the person who verified. This is the mechanism by which a legitimately verified account becomes an entry point into a farmed network — and it is invisible to any control that only looks at onboarding.

Account takeover. Credentials are phished or stuffed, and the attacker inherits a verified account with an established reputation and elevated limits. A verified account is a more attractive takeover target, not a less attractive one.

Escalation after the fact. The account that verified for modest access in January requests a 50× quota increase in August. Nothing about the January verification speaks to the August request.

In all three, the account's verification status is unchanged and the human behind it is not who you think. A password, a one-time code, or a session token cannot distinguish these cases, because every one of them is an attacker who legitimately holds the credential. Only a biometric check asks the question that matters: is the person here right now the person who verified?

How it works

Biometric Authentication reuses the same LivenessV3 and FaceMatchV3 components as the regular identity flow. The only difference is where the reference image comes from — instead of the portrait on a freshly submitted document, it uses the portrait already stored from the user's prior verification.

That is why it needs no documents, and why it is fast and cheap enough to sit in a normal product flow.

It is session-only

There is no dedicated /v3/biometric-auth/ endpoint. Authentication is delivered through a session whose workflow is configured for it — workflow_type=BIOMETRIC_AUTHENTICATION. If you are looking for a standalone endpoint in the API reference, this is why you cannot find one.

The flow

1. Configure a workflow of type BIOMETRIC_AUTHENTICATION in the console and note its workflow_id.
2. Create a session:

curl -X POST 'https://verification.didit.me/v3/session/' \
  -H 'x-api-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "workflow_id": "YOUR_BIOMETRIC_AUTH_WORKFLOW_ID",
    "vendor_data": "acct_8842",
    "callback": "https://yourplatform.example/auth/complete"
  }'

1. Send the user through the returned session — hosted, or embedded with any of the free SDKs.
2. Fetch the decision:

curl -X GET 'https://verification.didit.me/v3/session/{sessionId}/decision/' \
  -H 'x-api-key: YOUR_API_KEY'

Or subscribe to session.status.updated and take the webhook.

The one detail that breaks integrations

Use the same vendor_data as the user's original verification.

That value is how Didit retrieves the stored portrait to match against. A new or different vendor_data means there is no stored face to compare, and the flow cannot do what you asked for. If you need to override the stored reference deliberately, pass portrait_image explicitly — but the normal path is a stable vendor_data per account, set at onboarding and reused forever.

This is the argument for treating vendor_data as a first-class identifier in your own schema from day one. It is also what makes Face Search results map cleanly onto your accounts.

Reading the result

Results arrive in liveness_checks and face_matches. Both are always arrays — never singular objects — and each item carries a node_id so multi-instance workflows can disambiguate steps. Each is null until its step has produced data.

Warnings include LOW_LIVENESS_SCORE, face-attack alerts, blocklist matches, and low face-match similarity. Thresholds and decline actions are configurable, so you can run a stricter bar for a large credit grant than for a routine quota bump.

What should trigger a step-up

The value of this control depends almost entirely on trigger design. Too many and you have built a nuisance; too few and it never fires when it matters.

Access escalation — quota increases, credit grants, new API key issuance, tier upgrades, moving to a capability tier you treat as sensitive.

Account changes — a new privileged team member, a change of billing owner, a payout destination change, a password or MFA reset.

Behavioral alerts — the highest-value trigger. When your own traffic layer flags an account for concentrated querying or a distillation-shaped pattern, a biometric step-up asks the one question the traffic layer cannot: is the verified human still the one operating this account? A pass narrows the interpretation. A failure or an abandonment is itself a strong signal.

Linking signals — a session carrying DEVICE_RECOVERED_HIGH_CONFIDENCE, or a face that matched an existing verified user, has earned a step-up regardless of what the account is asking for.

Dormancy plus escalation — an account quiet for months that suddenly requests a large increase. Not dormancy alone; the combination.

Why not just require a password or a code?

Because every conventional factor is a bearer credential, and the threat model here is an attacker who holds the credential.

A one-time code goes to the phone number or address on file — which the attacker controls after a takeover, and which the legitimate key-sharer simply forwards. A password proves knowledge of a string. A hardware key proves possession of an object, which can be handed over with the key.

A liveness-checked face match proves that a specific human being is present at this moment. For binding privilege to a person, that is the only factor that answers the actual question. At $0.10 and under two seconds, it is also cheap enough to use on real triggers rather than saving it for emergencies.

What it does not do is worth stating too. Re-authenticating the human behind an account does not prevent model extraction and does not detect it. A verified developer can still misuse the access they hold. This closes the gap between "this account was verified once" and "this human is here now" — a narrow, real gap. Model-level output controls and semantic traffic detection remain separate layers, and they stay yours.

Use cases

AI API platforms gating quota escalation, credit grants and key issuance behind a check on the human.

Agent and automation products requiring a step-up before an agent is granted a new capability or a spending limit is raised.

Financial services re-authenticating before a high-value transfer or a payout-destination change.

Marketplaces re-verifying a seller before a payout method change — the most common account-takeover payoff.

Any platform with a recovery flow using biometric re-authentication instead of knowledge-based questions, which are the weakest link in most account-security designs.

Frequently asked questions

Does the user need to submit a document again?

No. That is the point. The check runs against the portrait already stored from their original verification — liveness plus face match, no documents.

What if the user was never verified with Didit?

Then there is no stored portrait and there is nothing to authenticate against. Biometric Authentication is a re-verification primitive; it presumes an earlier verification under the same vendor_data.

How long does it take?

Sub-two-second inference. From the user's point of view it is a selfie and a moment.

Can it run inside our own interface?

Yes. The web, iOS, Android, React Native and Flutter SDKs are all free, and White Label ($0.20) removes Didit branding.

What if someone holds up a photo or a video of the account owner?

That is what liveness detection is for. Didit's passive liveness holds an iBeta Level 1 presentation-attack-detection evaluation, and face-attack alerts surface in the warnings. Thresholds are configurable.

What does it cost?

$0.10 per authentication, pay-per-success, no minimum.

Should every login require this?

No. Login is the wrong trigger — it fires constantly and mostly on nothing. Attach it to privilege escalation and to alerts, where the cost of being wrong is high and the frequency is low.

Ready to get started?

Configure one workflow, wire it to your escalation points, and re-use it everywhere.

• Read the docs — Biometric Authentication overview and the Sessions API.
• See the product — User Verification.
• Check the pricing — $0.10 per authentication, pay-per-success, no minimums.
• Start free — business.didit.me, 500 KYC verifications a month at no cost.