SDK OAuth Scopes and Presets

Configure what user data your app can access using OAuth scopes. Complete list available presets including identity, KYC, financial, and social data.

Working with sandbox?. Create your credentials for testing directly from the Dashboard

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

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

You can use camel case when requesting scopes as well so, for example is_human can also be requested as isHuman .

identity:read

Grants access to basic identity verification presets.

Preset	Type	Description	Sandbox	Production
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	✅	✅
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	Sandbox	Production
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	Sandbox	Production
legal_name	string	Full legal name from identity verification	❌	❌

identity:address_postal_code

Preset	Type	Description	Sandbox	Production
address_postal_code	string	Postal/ZIP code	❌	❌

identity:address_full

Preset	Type	Description	Sandbox	Production
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	Sandbox	Production
document_number	string	ID document number (sensitive)	❌	❌

financial:net_worth

Grants access to net worth data and verification.

Preset	Type	Description	Sandbox	Production
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	Sandbox	Production
bank_balance_total	number	Total bank balance (USD)	❌	❌

financial:loan_balance

Preset	Type	Description	Sandbox	Production
loan_balance_total	number	Total loan balance (USD)	❌	❌
proof_of_mortgage	boolean	Whether user has verified mortgage	❌	❌

profile.full

Preset	Type	Description	Sandbox	Production
humanity_user	string[]	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

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

humanity_score

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

is_human

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

country_of_residence

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

age

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

address_postal_code

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

legal_name

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

residency_region

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

age_over_18

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

nationality

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

address_full

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

date_of_birth

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

email

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

phone

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

age_over_21

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

social_accounts

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

wallet_addresses

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

primary_wallet_address

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

palm_verified

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

KYC Presets

kyc_passed

{
  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

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

document_number

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

document_country

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

document_expiry_date

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

Financial Presets

net_worth_above_10k

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

net_worth_above_100k

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

net_worth_total

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

bank_balance_total

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

loan_balance_total

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

Legacy/Compound Presets

humanity_user

{
  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

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

proof_of_investments

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

proof_of_mortgage

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

proof_of_residency

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

proof_of_retirement

{ 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