# SDK OAuth Scopes and Presets

> Working with sandbox?. Create your credentials for testing directly [from the Dashboard ](https://app.humanity.org/sandbox)

## OAuth Scopes

Scopes control what data your application can request from users. When a user authorizes your app, they consent to sharing data covered by the requested scopes.

### Scope Model

* **Category scopes** (e.g., `identity:read`) grant access to all low/medium sensitivity presets in that category
* **Field-level scopes** (e.g., `identity:date_of_birth`) are required for high/critical sensitivity presets
* Derived fields are automatically available when the parent field scope is granted

***

## Available Scopes

### Core Scopes

<table><thead><tr><th width="372.640625">Scope</th><th>Description</th></tr></thead><tbody><tr><td><code>openid</code></td><td>Required for OpenID Connect flows</td></tr><tr><td><code>profile.full</code></td><td>Access to full Humanity profile</td></tr></tbody></table>

### Identity Scopes

| Scope                          | Sensitivity | Description                                                      |
| ------------------------------ | ----------- | ---------------------------------------------------------------- |
| `identity:read`                | Low/Medium  | Access to basic identity presets (email, phone, is\_human, etc.) |
| `identity:date_of_birth`       | High        | Access to date of birth and age-related presets                  |
| `identity:legal_name`          | High        | Access to legal name                                             |
| `identity:address_postal_code` | High        | Access to postal/ZIP code                                        |
| `identity:address_full`        | High        | Access to full verified address                                  |

### KYC Scopes

| Scope                 | Sensitivity | Description                                |
| --------------------- | ----------- | ------------------------------------------ |
| `kyc:read`            | Low/Medium  | Access to KYC status and document metadata |
| `kyc:document_number` | High        | Access to ID document number               |

### Financial Scopes

| Scope                    | Sensitivity | Description                             |
| ------------------------ | ----------- | --------------------------------------- |
| `financial:net_worth`    | High        | Access to net worth data and thresholds |
| `financial:bank_balance` | High        | Access to bank balance totals           |
| `financial:loan_balance` | High        | Access to loan balance totals           |

***

## Presets by Scope

Preset availability within each scope, across sandbox and production. ✅ available · ❌ not yet available.

### `identity:read`

Grants access to basic identity verification presets.

<table><thead><tr><th width="206.8515625">Preset</th><th width="102.7578125">Type</th><th width="226.81640625">Description</th><th width="113.04296875">Sandbox</th><th>Production</th></tr></thead><tbody><tr><td><code>humanity_uuid</code></td><td>string</td><td>User’s Humanity unique identifier</td><td>✅</td><td>✅</td></tr><tr><td><code>humanity_score</code></td><td>number</td><td>Confidence score for human verification</td><td>✅</td><td>✅</td></tr><tr><td><code>is_human</code></td><td>boolean</td><td>Whether user passed palm/vein verification</td><td>✅</td><td>✅</td></tr><tr><td><code>country_of_residence</code></td><td>string</td><td>Country of residence (ISO 3166-1 alpha-2)</td><td>✅</td><td>✅</td></tr><tr><td><code>nationality</code></td><td>string</td><td>Country of citizenship (ISO 3166-1 alpha-2)</td><td>✅</td><td>✅</td></tr><tr><td><code>residency_region</code></td><td>string</td><td>Region bucket (EU, APAC, NA, LATAM, OTHER)</td><td>✅</td><td>✅</td></tr><tr><td><code>email</code></td><td>string</td><td>Verified primary email address</td><td>✅</td><td>✅</td></tr><tr><td><code>phone</code></td><td>string</td><td>Verified primary phone (E.164 format)</td><td>✅</td><td>✅</td></tr><tr><td><code>social_accounts</code></td><td>array</td><td>Linked social account identifiers</td><td>✅</td><td>✅</td></tr><tr><td><code>wallet_addresses</code></td><td>array</td><td>User’s wallet addresses</td><td>✅</td><td>✅</td></tr><tr><td><code>primary_wallet_address</code></td><td>string</td><td>Primary wallet address</td><td>✅</td><td>✅</td></tr><tr><td><code>palm_verified</code></td><td>boolean</td><td>Whether user completed palm verification</td><td>✅</td><td>✅</td></tr><tr><td><code>proof_of_residency</code></td><td>boolean</td><td>Whether residency is verified</td><td>✅</td><td>✅</td></tr></tbody></table>

### `identity:date_of_birth`

Grants access to date of birth and derived age presets.

<table><thead><tr><th width="209.56640625">Preset</th><th width="101.7578125">Type</th><th width="226.58203125">Description</th><th width="114.40625">Sandbox</th><th>Production</th></tr></thead><tbody><tr><td><code>date_of_birth</code></td><td>date</td><td>Full date of birth (YYYY-MM-DD)</td><td>✅</td><td>❌</td></tr><tr><td><code>age</code></td><td>integer</td><td>User’s current age</td><td>✅</td><td>❌</td></tr><tr><td><code>is_18_plus</code></td><td>boolean</td><td>Whether user is 18 or older</td><td>✅</td><td>❌</td></tr><tr><td><code>is_21_plus</code></td><td>boolean</td><td>Whether user is 21 or older</td><td>✅</td><td>❌</td></tr></tbody></table>

### `identity:legal_name`

<table><thead><tr><th width="213.6484375">Preset</th><th width="97.0390625">Type</th><th width="233.37890625">Description</th><th width="107.60546875">Sandbox</th><th>Production</th></tr></thead><tbody><tr><td><code>legal_name</code></td><td>string</td><td>Full legal name from identity verification</td><td>❌</td><td>❌</td></tr></tbody></table>

### `identity:address_postal_code`

<table><thead><tr><th width="217.7265625">Preset</th><th width="97.7578125">Type</th><th width="231.01953125">Description</th><th width="108.96484375">Sandbox</th><th>Production</th></tr></thead><tbody><tr><td><code>address_postal_code</code></td><td>string</td><td>Postal/ZIP code</td><td>❌</td><td>❌</td></tr></tbody></table>

### `identity:address_full`

<table><thead><tr><th width="223.16796875">Preset</th><th width="97.48046875">Type</th><th width="227.6640625">Description</th><th width="108.9609375">Sandbox</th><th>Production</th></tr></thead><tbody><tr><td><code>address_full</code></td><td>string</td><td>Full verified address</td><td>❌</td><td>❌</td></tr></tbody></table>

### `kyc:read`

Grants access to KYC verification status and document metadata.

<table><thead><tr><th width="223.1640625">Preset</th><th width="98.8359375">Type</th><th width="234.45703125">Description</th><th width="104.88671875"></th><th></th></tr></thead><tbody><tr><td><code>kyc_passed</code></td><td>boolean</td><td>Overall KYC verification status</td><td>✅</td><td>✅</td></tr><tr><td><code>kyc_last_updated_at</code></td><td>datetime</td><td>Timestamp of last KYC update</td><td>✅</td><td>✅</td></tr><tr><td><code>document_country</code></td><td>string</td><td>Issuing country of identity document</td><td>❌</td><td>❌</td></tr><tr><td><code>document_expiry_date</code></td><td>date</td><td>Document expiration date</td><td>❌</td><td>❌</td></tr></tbody></table>

### `kyc:document_number`

<table><thead><tr><th width="223.16796875">Preset</th><th width="98.8359375">Type</th><th width="232.1015625">Description</th><th width="104.88671875">Sandbox</th><th>Production</th></tr></thead><tbody><tr><td><code>document_number</code></td><td>string</td><td>ID document number (sensitive)</td><td>❌</td><td>❌</td></tr></tbody></table>

### `financial:net_worth`

Grants access to net worth data and verification.

<table><thead><tr><th width="223.1640625">Preset</th><th width="98.8359375">Type</th><th width="231.73828125">Description</th><th width="104.8828125">Sandbox</th><th>Production</th></tr></thead><tbody><tr><td><code>net_worth_total</code></td><td>number</td><td>Total net worth (USD)</td><td>✅</td><td>✅</td></tr><tr><td><code>net_worth_above_10k</code></td><td>boolean</td><td>Whether net worth exceeds $10,000</td><td>✅</td><td>✅</td></tr><tr><td><code>net_worth_above_100k</code></td><td>boolean</td><td>Whether net worth exceeds $100,000</td><td>✅</td><td>✅</td></tr><tr><td><code>proof_of_assets</code></td><td>boolean</td><td>Whether user has verified assets</td><td>✅</td><td>✅</td></tr><tr><td><code>proof_of_investments</code></td><td>boolean</td><td>Whether user has verified investments</td><td>✅</td><td>✅</td></tr><tr><td><code>proof_of_retirement</code></td><td>boolean</td><td>Whether user has verified retirement savings</td><td>✅</td><td>✅</td></tr></tbody></table>

### `financial:bank_balance`

<table><thead><tr><th width="223.16796875">Preset</th><th width="98.83984375">Type</th><th width="233.45703125">Description</th><th width="104.88671875">Sandbox</th><th>Production</th></tr></thead><tbody><tr><td><code>bank_balance_total</code></td><td>number</td><td>Total bank balance (USD)</td><td>❌</td><td>❌</td></tr></tbody></table>

### `financial:loan_balance`

<table><thead><tr><th width="231.32421875">Preset</th><th width="100.2734375">Type</th><th width="229.09765625">Description</th><th width="104.88671875">Sandbox</th><th>Production</th></tr></thead><tbody><tr><td><code>loan_balance_total</code></td><td>number</td><td>Total loan balance (USD)</td><td>❌</td><td>❌</td></tr><tr><td><code>proof_of_mortgage</code></td><td>boolean</td><td>Whether user has verified mortgage</td><td>❌</td><td>❌</td></tr></tbody></table>

### `profile.full`

<table><thead><tr><th width="221.80859375">Preset</th><th width="103.91796875">Type</th><th width="231.1015625">Description</th><th width="106.24609375">Sandbox</th><th>Production</th></tr></thead><tbody><tr><td><code>humanity_user</code></td><td>string[]</td><td>Full Humanity profile access</td><td>✅</td><td>✅</td></tr></tbody></table>

***

## Example Scope Requests

### Minimal - Human Verification Only

```
scope=openid identity:read
```

Grants access to: `is_human`, `humanity_uuid`, `email`, `phone`, etc.

### Age Verification (21+)

```
scope=openid identity:date_of_birth
```

Grants access to: `age_over_21`, `age_over_18`, `age`, `date_of_birth`

### Full Identity Profile

```
scope=openid identity:read identity:date_of_birth identity:legal_name
```

Grants access to all identity presets including age and legal name.

### KYC Verification

```
scope=openid kyc:read
```

Grants access to: `kyc_passed`, `document_country`, `document_expiry_date`

### Financial Verification

```
scope=openid financial:net_worth
```

Grants access to: `net_worth_total`, `net_worth_above_10k`, `net_worth_above_100k`

### Comprehensive Access

```
scope=openid identity:read identity:date_of_birth kyc:read financial:net_worth
```

Grants access to identity, age, KYC status, and net worth presets.

***

## Preset Queries

All presets are defined as declarative queries evaluated by the query engine.

### Identity Presets

#### `humanity_uuid`

```tsx
{ check: { claim: 'identity.humanity_id', operator: 'get' } }
```

#### `humanity_score`

```tsx
{ check: { claim: 'identity.humanity_score', operator: 'get' } }
```

#### `is_human`

```tsx
{
  policy: {
    anyOf: [
      { check: { claim: 'identity.palm_verified', operator: '==', value: true } },
      { check: { claim: 'identity.vein_verified', operator: '==', value: true } },
    ],
  },
}
```

#### `country_of_residence`

```tsx
{ check: { claim: 'identity.country_of_residence', operator: 'get' } }
```

#### `age`

```tsx
{ check: { claim: 'identity.age', operator: 'get' } }
```

#### `address_postal_code`

```tsx
{ check: { claim: 'identity.postal_code', operator: 'get' } }
```

#### `legal_name`

```tsx
{ check: { claim: 'identity.legal_name', operator: 'get' } }
```

#### `residency_region`

```tsx
{ check: { claim: 'identity.region', operator: 'get' } }
```

#### `age_over_18`

```tsx
{ check: { claim: 'identity.age', operator: '>=', value: 18 } }
```

#### `nationality`

```tsx
{ check: { claim: 'identity.nationality', operator: 'get' } }
```

#### `address_full`

```tsx
{ check: { claim: 'identity.address', operator: 'get' } }
```

#### `date_of_birth`

```tsx
{ check: { claim: 'identity.date_of_birth', operator: 'get' } }
```

#### `email`

```tsx
{ check: { claim: 'identity.email', operator: 'get' } }
```

#### `phone`

```tsx
{ check: { claim: 'identity.phone', operator: 'get' } }
```

#### `age_over_21`

```tsx
{ check: { claim: 'identity.age', operator: '>=', value: 21 } }
```

#### `social_accounts`

```tsx
{ check: { claim: 'identity.social_accounts', operator: 'get' } }
```

#### `wallet_addresses`

```tsx
{ check: { claim: 'identity.wallet_addresses', operator: 'get' } }
```

#### `primary_wallet_address`

```tsx
{ check: { claim: 'identity.wallet_addresses', operator: 'get' } }
```

#### `palm_verified`

```tsx
{ check: { claim: 'identity.palm_verified', operator: '==', value: true } }
```

### KYC Presets

#### `kyc_passed`

```tsx
{
  policy: {
    anyOf: [
      { check: { claim: 'kyc.passed', operator: '==', value: true } },
      { check: { claim: 'kyc.status', operator: '==', value: 'verified' } },
      { check: { claim: 'kyc.status', operator: '==', value: 'passed' } },
      { check: { claim: 'kyc.status', operator: '==', value: 'approved' } },
      { check: { claim: 'kyc.status', operator: '==', value: 'complete' } },
    ],
  },
}
```

#### `kyc_last_updated_at`

```tsx
{ check: { claim: 'kyc.last_updated_at', operator: 'get' } }
```

#### `document_number`

```tsx
{ check: { claim: 'kyc.document_number', operator: 'get' } }
```

#### `document_country`

```tsx
{ check: { claim: 'kyc.document_country', operator: 'get' } }
```

#### `document_expiry_date`

```tsx
{ check: { claim: 'kyc.document_expiry', operator: 'get' } }
```

### Financial Presets

#### `net_worth_above_10k`

```tsx
{ check: { claim: 'financial.net_worth', operator: '>', value: 10000 } }
```

#### `net_worth_above_100k`

```tsx
{ check: { claim: 'financial.net_worth', operator: '>', value: 100000 } }
```

#### `net_worth_total`

```tsx
{ check: { claim: 'financial.net_worth', operator: 'get' } }
```

#### `bank_balance_total`

```tsx
{ check: { claim: 'financial.bank_balance', operator: 'get' } }
```

#### `loan_balance_total`

```tsx
{ check: { claim: 'financial.loan_balance', operator: 'get' } }
```

### Legacy/Compound Presets

#### `humanity_user`

```tsx
{
  policy: {
    allOf: [
      { check: { claim: 'identity.humanity_id', operator: 'exists' } },
      {
        policy: {
          anyOf: [
            { check: { claim: 'identity.palm_verified', operator: '==', value: true } },
            { check: { claim: 'identity.vein_verified', operator: '==', value: true } },
          ],
        },
      },
    ],
  },
}
```

#### `proof_of_assets`

```tsx
{ check: { claim: 'financial.net_worth', operator: '>', value: 0 } }
```

#### `proof_of_investments`

```tsx
{ check: { claim: 'financial.investment_balance', operator: '>', value: 0 } }
```

#### `proof_of_mortgage`

```tsx
{ check: { claim: 'financial.loan_balance', operator: '>', value: 0 } }
```

#### `proof_of_residency`

```tsx
{ check: { claim: 'identity.country_of_residence', operator: 'exists' } }
```

#### `proof_of_retirement`

```tsx
{ check: { claim: 'financial.retirement_balance', operator: '>', value: 0 } }
```

***

## Query Operators

| Operator       | Description                                                          |
| -------------- | -------------------------------------------------------------------- |
| **get**        | Returns the claim value if present (used for data retrieval presets) |
| **exists**     | Passes if claim value is present (not null/undefined)                |
| **==**         | Strict equality comparison                                           |
| **!=**         | Not equals comparison                                                |
| **>**          | Greater than (numeric)                                               |
| **>=**         | Greater than or equal (numeric)                                      |
| **<**          | Less than (numeric)                                                  |
| **<=**         | Less than or equal (numeric)                                         |
| **in**         | Value is in the provided array                                       |
| **notIn**      | Value is not in the provided array                                   |
| **contains**   | String/array contains the expected value                             |
| **startsWith** | String starts with the expected prefix                               |
| **regex**      | Value matches the regex pattern                                      |

***

## Notes

* **Scope Requirements**: Your application’s `allowedScopes` must include any scope you request. Configure this in the developer dashboard.
* **User Consent**: Users must explicitly approve each scope category during authorization.
* **`get` vs `exists`**: Use `get` when you need the actual value (e.g., email, phone). Use `exists` for presence checks in compound queries.
* **Claim Normalization**: The ClaimResolver normalizes incoming claim values to canonical types before evaluation.
* **Query Evaluation**: All presets are evaluated by the QueryEngineService using credentials from the user’s context.

## Claim Paths (Advanced)

Presets are built on top of a set of verified data points called **claim paths**.

Claim paths represent attributes that Humanity can evaluate against a user’s credentials, such as identity signals, KYC status, financial indicators, or connected accounts. Most integrations **do not need to work with claim paths directly**.

Presets provide a stable, opinionated way to request common checks (for example, `is_human` or `is_21_plus`) without dealing with underlying data structures.

**For advanced use cases**—such as composing more granular policies or understanding what data powers a preset—you can explore the full list of available claim paths in the Developer Dashboard.

[Developer Dashboard](https://developers.humanity.org/dashboard/queries/paths)


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.humanity.org/build-with-humanity/build-with-the-sdk-api/sdk-oauth-scopes-and-presets.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.