OAuth Scopes

Scope-based authorization model for accessing user data

Humanity Protocol uses a granular scope model to control access to user data. Apps request scopes during OAuth authorization, and users grant or deny access. Scopes determine which presets and data fields your application can access.

Scope Hierarchy

Scopes are organized into two levels:

1. Category scopes - Grant access to low/medium sensitivity fields in a category
2. Field-level scopes - Required for high/critical sensitivity fields

identity:read          → Basic identity (email, phone, country, wallet)
├── identity:date_of_birth  → DOB, age, age verification
├── identity:legal_name     → Full legal name
├── identity:address_postal_code → Postal/ZIP code
└── identity:address_full   → Complete address

Available Scopes

Category Scopes

Scope	Description	Fields Included
identity:read	Basic identity data	humanity_uuid, is_human, country_of_residence, email, phone, wallet_address, nationality
kyc:read	KYC verification status	kyc_passed, kyc_last_updated_at, document_country, document_expiry_date
financial:read	General financial data	Trading frequency, exchange balances

Field-Level Scopes (High Sensitivity)

Scope	Description	Fields Included
identity:date_of_birth	Date of birth and derived fields	date_of_birth, age, age_over_18, age_over_21
identity:legal_name	Legal name from ID verification	legal_name
identity:address_postal_code	Postal/ZIP code	address_postal_code
identity:address_full	Complete verified address	address_full
kyc:document_number	ID document number	document_number
financial:net_worth	Total net worth	net_worth_total, net_worth_above_10k, net_worth_above_100k
financial:bank_balance	Bank account balances	bank_balance_total
financial:loan_balance	Outstanding loans	loan_balance_total

Profile Scopes

Scope	Description
openid	Required for OpenID Connect ID tokens
profile.full	Complete user profile access
data.read	Raw data record access

Preset to Scope Mapping

Each preset requires a specific scope. Here’s the mapping:

Identity Presets

Preset	Required Scope
humanity_uuid, humanity_score, is_human	identity:read
country_of_residence, residency_region, nationality	identity:read
email, phone, wallet_address	identity:read
palm_verified, social_accounts	identity:read
date_of_birth, age, age_over_18, age_over_21	identity:date_of_birth
legal_name	identity:legal_name
address_postal_code	identity:address_postal_code
address_full	identity:address_full

KYC Presets

Preset	Required Scope
kyc_passed, kyc_last_updated_at	kyc:read
document_country, document_expiry_date	kyc:read
document_number	kyc:document_number

Financial Presets

Preset	Required Scope
net_worth_above_10k, net_worth_above_100k, net_worth_total	financial:net_worth
bank_balance_total	financial:bank_balance
loan_balance_total	financial:loan_balance

Requesting Scopes

Request scopes during OAuth authorization:

const { url } = sdk.buildAuthUrl({
  scopes: ['identity:read', 'identity:date_of_birth', 'kyc:read'],
  prompt: 'consent',
});

Or in the raw authorization URL:

GET /oauth/authorize?
  client_id=your_client_id&
  redirect_uri=https://yourapp.com/callback&
  response_type=code&
  scope=identity:read%20identity:date_of_birth%20kyc:read&
  code_challenge=...&
  code_challenge_method=S256

Scope Validation

When accessing presets or using the query engine, the API validates that:

1. The access token has the required scope for the requested data
2. The user has consented to share that data
3. The credential is valid and not expired

If validation fails, you’ll receive an E4003 error:

{
  "error": "insufficient_scope",
  "error_code": "E4003",
  "error_description": "Token does not have the required scope: identity:date_of_birth"
}

Sensitivity Levels

Scopes align with data sensitivity levels:

Sensitivity	Description	Example Scopes
low	Minimal privacy impact	Derived fields like age, residency_region
medium	Standard PII	identity:read, kyc:read
high	Sensitive PII	identity:date_of_birth, identity:legal_name, financial:*
critical	Highly sensitive	Tax IDs, SSN (restricted access)

Best Practices

1. Request minimal scopes - Only request what you need
2. Explain why - Use clear consent text explaining data usage
3. Handle scope downgrade - Users may grant fewer scopes than requested
4. Check granted_scopes - The token response includes actual granted scopes

const token = await sdk.exchangeCodeForToken({ code, codeVerifier });

// Check what was actually granted
if (!token.granted_scopes.includes('identity:date_of_birth')) {
  // Handle case where age verification isn't available
}

Discovery

Fetch available scopes from the discovery endpoint:

curl https://api.humanity.org/v2/.well-known/hp-configuration

The response includes scopes_supported and scopes_catalog with detailed metadata for each scope.