> ## Documentation Index
> Fetch the complete documentation index at: https://docs.didit.me/llms.txt
> Use this file to discover all available pages before exploring further.

# Verified Identity: Verify at Sign-Up and Step-Up Before Payouts

> Require a liveness or full ID check before an account exists, ask again before payouts and other sensitive actions, and get verified claims in tokens.

Didit Authentication's verified identity asks people to prove who they are at the moments you choose: before their account is created, and again before a sensitive action such as a payout.
Your app receives the outcome and the verified claims you selected, such as `over_18` or a verified name, in the person's tokens, never their documents or photos.

Set it up in the console under **Authentication > Verified identity**, or by API with [`verified/`](#set-it-up-by-api).

![The Verified identity page in the Didit Business Console, with the sign-up verification levels and their prices, and the step-up rules before sensitive actions](https://mintcdn.com/didit-0f962782/RpqZjIB1GnUPdMTN/images/authentication/console-verified-identity.png?fit=max\&auto=format\&n=RpqZjIB1GnUPdMTN\&q=85\&s=98544caeedf5ffaf68484cace19f9b3f)

Authentication > Verified identity: the check at sign-up and the rules before sensitive actions.

## How it works

Every check runs as a verification session of your own application, created with the person's `vendor_data`.
That means it appears in your verifications and on the same person as their sign-ins and transactions, goes to manual review like any other verification, and is billed at that verification's price.

| Check | What the person does | Price at list |
| - | - | - |
| Liveness | Takes one selfie, checked for liveness. | \$0.10 |
| Selfie login | Takes a selfie that Didit matches to the face it already holds for the person. | \$0.10 |
| Full ID | Scans an identity document and takes a selfie: document, liveness and face match. | \$0.33 |

Didit runs each check with its default workflow, or with one of your own workflows that you pick for that check.
See [pricing](https://docs.didit.me/getting-started/pricing.md) for every verification price.

## At sign-up

Choose the level a person must pass before their account is created:

| Level | Value | Meaning |
| - | - | - |
| No verification | `none` | Anyone with an email, a phone or a passkey can sign up. The default. |
| Liveness | `liveness` | A real person signs up: one selfie, checked for liveness. |
| Full ID | `full_id` | Document, liveness and face match, before the account exists. |

A new level applies to people who sign up from then on, never to existing accounts.

On the hosted pages, Didit sends the person through the check during sign-up.
On your own screens, the sign-up call answers `verification_required` with a `verification_url` that works for 30 minutes: send the person there.
Didit issues the sign-in code only after the check is approved.

## Step-up before sensitive actions

A step-up asks the person to verify again, only when an action is risky enough.
You turn on the rules, and your app asks Didit before each sensitive action whether one applies.

![A phone showing a step-up that asks the person to confirm it is them with a selfie](https://mintcdn.com/didit-0f962782/RpqZjIB1GnUPdMTN/images/authentication/step-up-preview.png?fit=max\&auto=format\&n=RpqZjIB1GnUPdMTN\&q=85\&s=dd5087d0ba5f20b49bbd4252149ef8ca)

What a person sees when a step-up asks for a selfie.

| Rule | Asks when | Default check |
| - | - | - |
| `payout` | A withdrawal or transfer is above your threshold, for example 500 in your currency. A payout in another currency is always checked. | Selfie login |
| `device` | A payout is made in a session on a device none of the person's earlier sessions came from. | Selfie login |
| `bank` | The person adds or changes a bank account. | Full ID |
| `contact` | The person changes their email address or phone number. | Liveness |

You can change the check of each rule to liveness, selfie login or full ID.
When several rules apply, Didit asks for the strongest check.
When Didit holds no face for the person yet, a selfie login becomes a full ID check.

### Ask for a step-up

Your app calls `POST {issuer}/step-up/` with the person's access token, or the SDKs' `stepUp()` method:

```bash theme={null}
curl --fail-with-body "${DIDIT_AUTH_ISSUER}/step-up/" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"action": "payout", "amount": "900.00", "currency": "USD", "return_to": "https://app.example.com/payouts/confirm"}'
```

| Field | Rule |
| - | - |
| `action` | `payout`, `bank` or `contact`. A payout also applies the `device` rule. |
| `amount` | Required for `payout`, with up to two decimals. |
| `currency` | ISO 4217 code. Defaults to the currency of your payout rule. |
| `return_to` | Where the person returns after verifying. When a rule applies, it must be one of your registered [redirect URLs](https://docs.didit.me/authentication/overview.md#redirect-urls). |

* `200 {"required": false}`: no rule applies, so go ahead.
* `201` with `verification_url`: send the person there. The step-up stays open for 30 minutes (`expires_in: 1800`).

### Read the result on your backend

The person comes back to `return_to` with `step_up=<id>&status=approved` added, but that query proves nothing.
Your backend reads the step-up with `GET {issuer}/step-up/{step_up_id}/` and an access token of the same session, and acts only when `status` is `approved`.

| Status | Meaning |
| - | - |
| `pending` | The person has not finished the check yet. |
| `approved` | The person passed. Go ahead with the action. |
| `review` | The check waits for your team's review. |
| `declined` | The person did not pass. It is not final while `verification_url` still works: they can try again, and the step-up returns to `pending`. |
| `expired` | The 30 minutes passed. Create a new step-up. |
| `superseded` | Another check took over, or the result was not for this step-up. Create a new one. |

A step-up never fails open: when verification is unavailable, the action stays blocked.
The [JavaScript](https://docs.didit.me/authentication/quickstarts/javascript.md#step-up-and-reauthentication), [Next.js](https://docs.didit.me/authentication/quickstarts/nextjs.md#step-up-before-sensitive-actions) and [iOS](https://docs.didit.me/authentication/quickstarts/ios.md#step-up-before-sensitive-actions) quickstarts show the SDK side, and the [API reference](https://docs.didit.me/authentication/api-reference/create-step-up.md) has the full contract.

## What your app receives

Choose which verified claims go into the person's tokens:

| Claim | Value |
| - | - |
| `over_18`, `over_21` | Whether the person is at least 18, or 21, from the verified date of birth. |
| `given_name`, `family_name` | The verified first and last name. |
| `birthdate` | The date of birth from the document, `YYYY-MM-DD`. |
| `nationality` | ISO 3166-1 alpha-2 code. |
| `country` | ISO 3166-1 alpha-2 code of the document's country. |
| `document_verified` | Whether an identity document was verified. |
| `liveness` | Whether a liveness check was passed. |

The access token and the ID token carry them in `verified`, with `level`, the highest level the person passed: `liveness`, `liveness_face_match` or `full_id`.
It is `{}` when the person has passed none, and `GET /session/` returns `null` instead.

```json theme={null}
{
  "verified": {
    "level": "full_id",
    "over_18": true,
    "given_name": "Alex",
    "country": "ES"
  }
}
```

* A check approved during a session reaches the tokens at the next refresh, within 5 minutes.
* Anything that holds the token can read these claims, your front end included, so select only the personal claims your app needs.
* Your app gets claims, never the document, the selfie or the face data.

## Set it up by API

`GET` and `PATCH` on `verified/` in your application's [Authentication management API](https://docs.didit.me/authentication/set-up-by-api.md) read and change the same settings as the console:

```bash theme={null}
curl --fail-with-body --request PATCH "${MANAGEMENT_BASE}verified/" \
  -H "x-api-key: $DIDIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "signup_level": "liveness",
    "rules": [
      {"rule": "payout", "enabled": true, "method": "selfie", "threshold": "500.00", "currency": "USD"},
      {"rule": "bank", "enabled": true, "method": "full_id"}
    ],
    "claims": ["over_18", "given_name", "country"]
  }'
```

| Field | Values |
| - | - |
| `signup_level` | `none`, `liveness` or `full_id`. |
| `rules` | One entry per rule you change: `rule` (`payout`, `device`, `bank` or `contact`), `enabled`, `method` (`liveness`, `selfie` or `full_id`), and for `payout` only, `threshold` and `currency`. |
| `claims` | The claims to put in tokens, from the table above. |
| `workflows` | Optional: your own workflow ID for `liveness`, `selfie` or `full_id`, or `null` for Didit's default. |

A rule you leave out keeps its current settings.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.