OAuth Scopes and Presets

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

identity:read

Grants access to basic identity verification presets.

Preset	Type	Description
humanity_uuid	string	User’s Humanity Protocol 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
age_over_18	boolean	Whether user is 18 or older
age_over_21	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

{ 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