> For the complete documentation index, see [llms.txt](https://devcenter.unico.io/you/Ol1H6eGO4sQvPYB1Nmyl/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://devcenter.unico.io/you/Ol1H6eGO4sQvPYB1Nmyl/authentication/build-with-llm.md).

# Build with LLM

Paste one of the prompts below into Claude Code, Codex, or Cursor to ship the full integration.

{% code title="prompt-you-authentication.md" overflow="wrap" expandable="true" %}

````
# Authenticate with Unico Human Tokenization — Console Login

You are helping a user authenticate with the Unico You Console. Before doing anything else, ask the following questions and wait for the answers:

> **1. Are you signing up for the first time (new account) or signing in to an existing account?**
> Reply with **signup** or **signin**.
>
> **2. (Only if signing in) Which authentication method do you prefer?**
> - **biometric** — face capture via the Unico SDK
> - **email** — one-time code sent to your registered email address

Then follow the matching section below.

- **SIGNUP** always uses biometric. Steps 1–2 require face capture; the link is sent to the provided email.
- **SIGNIN via biometric**: Steps 1–2 require face capture; the link is returned in the API response.
- **SIGNIN via email**: send the OTP to the registered email, then validate the code — no biometric capture required.

> **Note for AI agents:** Biometric steps (SIGNUP and SIGNIN via biometric) require a human to complete face capture — this cannot be automated. After Step 1, hand the link to the user (from the email for SIGNUP, or from `session.link` for SIGNIN biometric), then either wait for their confirmation or poll Step 2 yourself while they complete the capture. The email OTP flow (SIGNIN via email) can be automated end-to-end if the agent has access to the user's inbox.

---

## My environment

```
Environment: [uat | production]
```

Base URL:
- UAT: `https://api.you.uat.unico.app`
- Production: `https://api.you.unico.app`

---

## If SIGNUP — First-time registration + organization setup

Use this flow when the user does not yet have a You Console account. By the end you will have a valid `authToken` and an `x-unico-accesskey`.

### What you need before starting

- Work email address (used to identify the account and receive the biometric capture link)
- Full name of the account owner
- Company name
- Website URL
- Country code — any [ISO 3166-1 alpha-3](https://en.wikipedia.org/wiki/List_of_ISO_3166_country_codes) code (e.g. `BRA`, `USA`, `MEX`, `DEU`, `IND`)
- Tax ID — optional (e.g. CNPJ for Brazil)
- Logo — URL (optional)
- Domains allowed to use the SDK (optional, e.g. `https://app.yourcompany.com`)

---

### Step 1 — Start a signup session

```bash
curl -X POST <BASE_URL>/api/console/v1/auth/biometric/sessions \
  -H "Content-Type: application/json" \
  -d '{
    "intent": "LOGIN_INTENT_SIGNUP",
    "email": "<email>",
    "name": "<name>"
  }'
```

> If this email is already registered, the request returns `400 Bad Request`. Use the SIGNIN flow instead.

**Expected response:**
```json
{
  "session": {
    "sessionId": "<sessionId>",
    "link": "",
    "token": ""
  }
}
```

`link` and `token` are empty for SIGNUP. The biometric capture link has been sent to `<email>`. Ask the user to check their inbox, open the link, and complete the face capture. Then proceed to Step 2.

---

### Step 2 — Poll until the session is resolved

Replace `<sessionId>` with the value from Step 1. Poll every 2–3 seconds.

```bash
curl <BASE_URL>/api/console/v1/auth/biometric/sessions/<sessionId>
```

Parse the response with a real JSON parser (e.g. `jq`) — not regex/string matching. The API's JSON formatting (whitespace, key order) is not a stable contract, and a hand-rolled extraction can silently fail to detect a resolved session, making the poll loop appear stuck.

Keep polling until `status` is `completed` and `outcome` is `matched`.

| `status` | `outcome` | Action |
|---|---|---|
| `pending` or `processing` | `pending` | Wait 2–3 seconds and poll again |
| `completed` | `matched` | Proceed to Step 3 — save `authToken` |
| `completed` | `no_match` | Biometric not recognized. Go back to Step 1 |
| `completed` | `inconclusive` | Could not be resolved. Go back to Step 1 |
| `expired` | — | Link expired. Go back to Step 1 |

> **SIGNUP-specific error:** If `GetBiometricLogin` returns `400 Bad Request` — "email already registered" — the biometric identity captured is already associated with an existing account. Ask the user to use the SIGNIN flow instead.

**Expected successful response:**
```json
{
  "result": {
    "sessionId": "<sessionId>",
    "status": "completed",
    "outcome": "matched",
    "authToken": "<authToken>"
  }
}
```

Save `authToken` — use it as `x-console-authorization: <authToken>` in Steps 3 and 4.

---

### Step 3 — Create your organization

> **This call can only be made once.** It provisions your tenant and generates your `branchId`.
> Confirm the organization details below with the user before sending this request — it is irreversible.

Fill in your organization details:

```
Company name: [name]
Work email: [responsibleEmail]
Website URL: [websiteUrl]
Country code: [ISO 3166-1 alpha-3, e.g. BRA | USA | MEX | DEU | IND]
Tax ID: [optional]
Logo: [URL — optional]
Allowed domains (optional, comma-separated): [allowedDomains]
```

```bash
curl -X POST <BASE_URL>/api/console/v1/organization \
  -H "x-console-authorization: <authToken>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "<name>",
    "responsibleEmail": "<responsibleEmail>",
    "websiteUrl": "<websiteUrl>",
    "countryCode": "<countryCode>",
    "logo": "<logoUrl>",
    "allowedDomains": ["<domain1>"]
  }'
```

**Expected response:**
```json
{
  "organization": {
    "id": "<organizationId>",
    "name": "<name>",
    "branchId": "<branchId>",
    "tenantId": "<tenantId>",
    ...
  }
}
```

Save `branchId` — you will need it when creating branches or branch-specific access keys.

---

### Step 4 — Create an access key

Provide a label to identify this key (e.g. `production-key`, `staging-key`).

```bash
curl -X POST <BASE_URL>/api/console/v1/access-keys \
  -H "x-console-authorization: <authToken>" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "<label>"
  }'
```

**Expected response:**
```json
{
  "accessKey": "<accessKey>"
}
```

> **The `accessKey` is returned only once.** Store it immediately in your secrets manager as `YOU_ACCESS_KEY`.
> It will not be shown again — if lost, you must rotate or revoke and create a new one.

---

### You're done (SIGNUP)

| Value | Variable | Where to use |
|---|---|---|
| `accessKey` | `YOU_ACCESS_KEY` | `x-unico-accesskey` header in all Human Tokenization requests |

Store this value in your secrets manager. Never commit it to source control or expose it to the browser.

To continue, see the [Human Tokenization integration guide](https://devcenter.unico.io/human-tokenization/you-api/api-reference/build-with-llm).

---

### Optional — Manage branches

Branches let you segment your organization's configuration per product or environment. The branch is resolved automatically from the access key used in the request — no need to pass `branchId` in `CreateProcess`.

> **Ask the user:** "Would you like to create additional branches for your organization (e.g. separate configurations for mobile, web, or staging)?"
> If yes, proceed below. If no, skip to the end-to-end test section.

#### Create a branch

```bash
curl -X POST <BASE_URL>/api/console/v1/organization/branches \
  -H "x-console-authorization: <authToken>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "<branchName>",
    "logo": "<logoUrl>",
    "allowedDomains": ["<domain1>"]
  }'
```

**Expected response:**
```json
{
  "branchId": "<branchId>"
}
```

Save `branchId` — use it when creating a branch-specific access key.

#### Update a branch

```bash
curl -X PUT <BASE_URL>/api/console/v1/organization/branches \
  -H "x-console-authorization: <authToken>" \
  -H "Content-Type: application/json" \
  -d '{
    "branchId": "<branchId>",
    "name": "<updatedName>",
    "logo": "<updatedLogoUrl>",
    "allowedDomains": ["<domain1>", "<domain2>"]
  }'
```

#### Create a branch-specific access key

```bash
curl -X POST <BASE_URL>/api/console/v1/access-keys \
  -H "x-console-authorization: <authToken>" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "<label>",
    "branchId": "<branchId>"
  }'
```

**Expected response:**
```json
{
  "accessKey": "<accessKey>"
}
```

> **The `accessKey` is returned only once.** Store it immediately. Any `CreateProcess` request authenticated with this key will automatically use the configuration of the associated branch.

---

---

## If SIGNIN via biometric — Returning user, face capture

Use this flow when the user already has a You Console account and wants to authenticate with face recognition.

---

### Step 1 — Start a signin session

```bash
curl -X POST <BASE_URL>/api/console/v1/auth/biometric/sessions \
  -H "Content-Type: application/json" \
  -d '{
    "intent": "LOGIN_INTENT_SIGNIN"
  }'
```

**Expected response:**
```json
{
  "session": {
    "sessionId": "<sessionId>",
    "link": "<link>",
    "token": "<sdkToken>"
  }
}
```

Open `link` in your browser and complete the biometric capture (face recognition). Then proceed to Step 2.

---

### Step 2 — Poll until the session is resolved

Replace `<sessionId>` with the value from Step 1. Poll every 2–3 seconds.

```bash
curl <BASE_URL>/api/console/v1/auth/biometric/sessions/<sessionId>
```

Parse the response with a real JSON parser (e.g. `jq`) — not regex/string matching. The API's JSON formatting (whitespace, key order) is not a stable contract, and a hand-rolled extraction can silently fail to detect a resolved session, making the poll loop appear stuck.

Keep polling until `status` is `completed` and `outcome` is `matched`.

| `status` | `outcome` | Action |
|---|---|---|
| `pending` or `processing` | `pending` | Wait 2–3 seconds and poll again |
| `completed` | `matched` | Login successful — save `authToken` |
| `completed` | `no_match` | Biometric not recognized. Go back to Step 1 |
| `completed` | `inconclusive` | Could not be resolved. Go back to Step 1 |
| `expired` | — | Link expired. Go back to Step 1 |

> **SIGNIN-specific error:** If `GetBiometricLogin` returns `400 Bad Request` — "user not found" — the biometric identity has no registered account. Ask the user to use the SIGNUP flow instead.

**Expected successful response:**
```json
{
  "result": {
    "sessionId": "<sessionId>",
    "status": "completed",
    "outcome": "matched",
    "authToken": "<authToken>"
  }
}
```

Save `authToken` — use it as `x-console-authorization: <authToken>` in all Console API requests.

---

### You're done (SIGNIN via biometric)

You now have a valid `authToken`. Use it as the `x-console-authorization` header in all authenticated Console API calls (organization management, access key management, etc.).

---

---

## If SIGNIN via email — Returning user, OTP code

Use this flow when the user already has a You Console account and wants to authenticate with a one-time code sent to their registered email. **Signup is not supported via email OTP** — use the SIGNUP biometric flow for first-time registration.

---

### What you need before starting

- Registered email address of the account

---

### Step 1 — Send the OTP

```bash
curl -X POST <BASE_URL>/api/console/v1/auth/email/sessions \
  -H "Content-Type: application/json" \
  -d '{
    "email": "<email>"
  }'
```

> If the email is not registered, `GetEmailLogin` will return `404 Not Found`. Ask the user to use the SIGNUP biometric flow instead.

**Expected response:**
```json
{
  "session": {
    "sessionId": "<sessionId>"
  }
}
```

Save `sessionId`. A 6-digit code has been sent to `<email>`. Ask the user to check their inbox and provide the code.

---

### Step 2 — Validate the OTP

Replace `<sessionId>` and `<code>` with the values from Step 1 and the user's inbox.

```bash
curl <BASE_URL>/api/console/v1/auth/email/sessions/<sessionId>/<code>
```

| HTTP | Condition | Action |
|---|---|---|
| `200` | Code valid — `authToken` present | Proceed — save `authToken` |
| `400` | Wrong code (`invalid otp code`) | Ask the user to check the code and retry |
| `400` | OTP already used, max attempts reached, or expired | Go back to Step 1 |
| `404` | Email not registered | Use the SIGNUP biometric flow |

**Expected successful response:**
```json
{
  "result": {
    "sessionId": "<sessionId>",
    "status": "completed",
    "outcome": "matched",
    "authToken": "<authToken>"
  }
}
```

Save `authToken` — use it as `x-console-authorization: <authToken>` in all Console API requests.

---

### You're done (SIGNIN via email)

You now have a valid `authToken`. Use it as the `x-console-authorization` header in all authenticated Console API calls (organization management, access key management, etc.).

---

---

## Optional — Test your credentials end-to-end

> **Ask the user:** "Would you like to run a quick end-to-end test to confirm your `accessKey` is working? You will complete a biometric capture and receive a `humanToken`."
> If they say yes, proceed below. If no, point them to the [Human Tokenization integration guide](./prompt-you-personid.md).

You will need:
- `YOU_ACCESS_KEY` — the `accessKey` obtained in Step 4 of the SIGNUP flow
- A browser to complete the biometric capture

---

### Test Step 1 — Create a process

```bash
curl -X POST <BASE_URL>/api/public/v1/process \
  -H "x-unico-accesskey: $YOU_ACCESS_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "scopes": ["SCOPE_HUMAN_TOKEN"],
    "redirectUrl": "https://example.com"
  }'
```

**Expected response:**
```json
{
  "id": "<processId>",
  "token": "<sdkToken>",
  "link": "<captureLink>"
}
```

Save `id`. Open `link` in your browser and complete the biometric capture. Then proceed to Test Step 2.

---

### Test Step 2 — Poll until completed

Replace `<processId>` with the value from Test Step 1. Poll every 2–3 seconds.

```bash
curl <BASE_URL>/api/public/v1/process/<processId> \
  -H "x-unico-accesskey: $YOU_ACCESS_KEY"
```

Keep polling until `status` is `completed`.

| `status` | Action |
|---|---|
| `pending` or `processing` | Wait 2–3 seconds and poll again |
| `completed` | Proceed — read `humanToken` below |
| `expired` | Link expired. Go back to Test Step 1 |
| `canceled` | Capture was canceled. Go back to Test Step 1 |

**Expected successful response:**
```json
{
  "id": "<processId>",
  "status": "completed",
  "data": {
    "humanToken": {
      "value": "<humanToken>",
      "status": "validated"
    }
  }
}
```

If `data.humanToken.value` is a non-empty string, your credentials are working correctly.

> **Note:** An empty `humanToken.value` means the biometric capture did not produce a reliable identifier (liveness check). Retry from Test Step 1.

---

### Test complete

Your setup is confirmed. To build the full integration, see the [Onboarding integration guide](https://devcenter.unico.io/you/Ol1H6eGO4sQvPYB1Nmyl/you-api/api-reference/data-collection-onboarding-flow) or [PIX payment guide](https://devcenter.unico.io/you/Ol1H6eGO4sQvPYB1Nmyl/you-api/api-reference/pix-payment-flow) or [card payment guide](https://devcenter.unico.io/you/Ol1H6eGO4sQvPYB1Nmyl/you-api/api-reference/card-payment-flow).

````

{% endcode %}