# 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

| Scope          | Description                       |
| -------------- | --------------------------------- |
| `openid`       | Required for OpenID Connect flows |
| `profile.full` | Access to full Humanity profile   |

### 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

### `identity:read`

Grants access to basic identity verification presets.

| Preset                   | Type    | Description                                 |
| ------------------------ | ------- | ------------------------------------------- |
| `humanity_uuid`          | string  | User’s Humanity unique identifier           |
| `humanity_score`         | number  | Confidence score for human verification     |
| `is_human`               | boolean | Whether user passed palm/vein verification  |
| `country_of_residence`   | string  | Country of residence (ISO 3166-1 alpha-2)   |
| `nationality`            | string  | Country of citizenship (ISO 3166-1 alpha-2) |
| `residency_region`       | string  | Region bucket (EU, APAC, NA, LATAM, OTHER)  |
| `email`                  | string  | Verified primary email address              |
| `phone`                  | string  | Verified primary phone (E.164 format)       |
| `social_accounts`        | array   | Linked social account identifiers           |
| `wallet_addresses`       | array   | User’s wallet addresses                     |
| `primary_wallet_address` | string  | Primary wallet address                      |
| `palm_verified`          | boolean | Whether user completed palm verification    |
| `proof_of_residency`     | boolean | Whether residency is verified               |

### `identity:date_of_birth`

Grants access to date of birth and derived age presets.

| Preset          | Type    | Description                     |
| --------------- | ------- | ------------------------------- |
| `date_of_birth` | date    | Full date of birth (YYYY-MM-DD) |
| `age`           | integer | User’s current age              |
| `is_18_plus`    | boolean | Whether user is 18 or older     |
| `is_21_plus`    | boolean | Whether user is 21 or older     |

### `identity:legal_name`

| Preset       | Type   | Description                                |
| ------------ | ------ | ------------------------------------------ |
| `legal_name` | string | Full legal name from identity verification |

### `identity:address_postal_code`

| Preset                | Type   | Description     |
| --------------------- | ------ | --------------- |
| `address_postal_code` | string | Postal/ZIP code |

### `identity:address_full`

| Preset         | Type   | Description           |
| -------------- | ------ | --------------------- |
| `address_full` | string | Full verified address |

### `kyc:read`

Grants access to KYC verification status and document metadata.

| Preset                 | Type     | Description                          |
| ---------------------- | -------- | ------------------------------------ |
| `kyc_passed`           | boolean  | Overall KYC verification status      |
| `kyc_last_updated_at`  | datetime | Timestamp of last KYC update         |
| `document_country`     | string   | Issuing country of identity document |
| `document_expiry_date` | date     | Document expiration date             |

### `kyc:document_number`

| Preset            | Type   | Description                    |
| ----------------- | ------ | ------------------------------ |
| `document_number` | string | ID document number (sensitive) |

### `financial:net_worth`

Grants access to net worth data and verification.

| Preset                 | Type    | Description                                  |
| ---------------------- | ------- | -------------------------------------------- |
| `net_worth_total`      | number  | Total net worth (USD)                        |
| `net_worth_above_10k`  | boolean | Whether net worth exceeds $10,000            |
| `net_worth_above_100k` | boolean | Whether net worth exceeds $100,000           |
| `proof_of_assets`      | boolean | Whether user has verified assets             |
| `proof_of_investments` | boolean | Whether user has verified investments        |
| `proof_of_retirement`  | boolean | Whether user has verified retirement savings |

### `financial:bank_balance`

| Preset               | Type   | Description              |
| -------------------- | ------ | ------------------------ |
| `bank_balance_total` | number | Total bank balance (USD) |

### `financial:loan_balance`

| Preset               | Type    | Description                        |
| -------------------- | ------- | ---------------------------------- |
| `loan_balance_total` | number  | Total loan balance (USD)           |
| `proof_of_mortgage`  | boolean | Whether user has verified mortgage |

### `profile.full`

| Preset          | Type    | Description                  |
| --------------- | ------- | ---------------------------- |
| `humanity_user` | boolean | Full Humanity profile access |

***

## 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)