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

# Overview

> How the Sardine Universal Identity integration works end-to-end

The Sardine Identity integration lets you collect and reuse verified user identities through a hosted widget backed by a simple server-side API. Your backend holds the credentials; your frontend never touches them.

There are two flows:

* **`kyc_input`** — A new user verifies their identity for the first time. The widget collects personal information, captures a government ID, and runs a liveness check.
* **`kyc_sharing`** — A returning Sardine network user has already been verified by another partner. They consent to share their existing verified identity with you. This takes seconds.

Both flows produce the same result: a verified identity you can retrieve via `GET /identity/entities/{customerId}`.

## Architecture

```mermaid theme={null}
sequenceDiagram
  actor U as User
  participant C as Your Backend
  participant S as api.sardine.ai
  participant W as identity.sardine.ai

  note over C,S: Server-side setup
  C->>S: POST /identity/entities (phoneNumber)
  S-->>C: { customerId }

  note over C,W: Generate widget URL
  C->>S: POST /identity/consents/widget (customerId, scope, flow)
  S-->>C: { widgetUrl }
  C-->>U: Redirect user to widgetUrl

  note over U,W: User completes verification
  U->>W: Verifies identity (ID scan, liveness, etc.)
  W-->>U: Redirects to successUrl

  note over C,S: Retrieve verified data
  C->>S: GET /identity/entities/{customerId}
  S-->>C: { profile, documentData, documentKyc }
```

## Key Concepts

**customerId** — A Sardine-assigned UUID created when you register a user via `POST /identity/entities`. Store this against your own user record; you'll use it for all subsequent API calls.

**scope** — Controls which data the widget collects or shares. Common combinations:

* `["profile"]` — Personal info only (name, DOB, address, email, phone)
* `["profile", "doc_kyc"]` — Full KYC with government ID and liveness check
* `["doc_kyc"]` — Document scan only (for users whose basic profile is already on file)

**flow** — `kyc_input` for new verifications, `kyc_sharing` for reusing an existing verified identity from the Sardine network.

**widgetUrl** — A one-time URL generated server-side. Redirect the user to this URL or embed it in an iframe. The URL encodes a session token and consent ID — it does not need to be kept secret but should be used promptly.

## Next Steps

* [Quickstart](/integration_guides/identity/quickstart) — Go live in four steps
* [API Integration](/integration_guides/identity/api_integration) — Full implementation reference