Scopes available

Complete reference for ZYKAY verification scopes.

What is a scope?

A scope defines what identity information you want to verify. Scopes are specified via the widget's data-scopes attribute and determine the attributes returned in the Exchange API response.

<script src="https://widget-app.zykay.com/v4/loader.min.js"
        data-partner-id="pk_live_xxx"
        data-success-path="/verified"
        data-scopes="isAdult,isFrench,isUnique"></script>

Scope table

Scope	Kind	Description	Returned attribute	PDF	EUDI Wallet
`isAdult`	Binary	At 18 years or older	`age_over_18: true`	Yes	Yes
`isFrench`	Binary	French nationality	`is_french: true`	Yes	Yes
`isEU`	Binary	Citizen of the European Union	`is_eu: true`	Yes	Yes
`isMale`	Binary	Male gender	`is_male: true`	Yes	No
`isFemale`	Binary	Female gender	`is_female: true`	Yes	No
`isUnique`	Nullify	Unique identifier per application	`nullifier: "0x..."`	Yes	Yes
`revealNationality`	Disclosure	ISO 3166-1 alpha-3 nationality code	`nationality: "FRA"`	Yes	No
`revealBirthYear`	Disclosure	Year of birth	`birth_year: 1990`	Yes	No

🚫

The isMale, isFemale, revealNationality and revealBirthYear scopes are not available with the EUDI Wallet. If you include them in data-scopes with data-client-proof-mode="true", the check will fail.

⚠️

The isMale and isFemale scopes are mutually exclusive. You cannot request both at the same time.

Binary scopes

Binary scopes return true or false. These are the most common:

isAdult — verifies that the user is 18 years or older. Default scope if data-scopes is not specified.
isFrench — verifies that the nationality is French (ISO 250 code).
isEU — verifies that the nationality is that of one of the 27 Member States of the European Union.
isMale / isFemale — checks gender. Only available with PDF verification.

Scope `isUnique` (Sybil resistance)

The isUnique scope generates a cryptographic identifier (nullifier) which is:

Unique per application: two different partner sites produce different nullifiers for the same user
Unique per user: two different users produce different nullifiers
Deterministic: the same user on the same site always produces the same nullifier

This allows duplicates (Sybil attacks) to be detected without revealing the user's identity.

The isUnique scope requires an app_id which is automatically derived from your Partner ID. No additional configuration is required.

Disclosure scopes

Disclosure scopes return a concrete value (not a boolean). They are only available with PDF verification:

revealNationality — returns the ISO 3166-1 alpha-3 nationality code (ex: "FRA", "DEU", "ITA")
revealBirthYear — returns the year of birth (ex: 1990)

Examples of combinations

<!-- Age verification only (default scope) -->
data-scopes="isAdult"
 
<!-- Age + French nationality -->
data-scopes="isAdult,isFrench"
 
<!-- Age + nationality + Sybil resistance (recommended for EUDI Wallet) -->
data-scopes="isAdult,isFrench,isUnique"
 
<!-- EU citizen + Sybil resistance -->
data-scopes="isEU,isUnique"
 
<!-- Age + sex (PDF only) -->
data-scopes="isAdult,isMale"

API response according to scopes

Example responses POST /v1/exchange for different scope combinations:

{
  "pass_token": "p_xyz789abc123...",
  "expires_in": 14400,
  "token_type": "Bearer",
  "age_over_18": true,
  "scopes": ["isAdult"],
  "attributes": {
    "age_over_18": true
  }
}

Next steps

Frontend integration — widget and attributes configuration
Backend (Exchange API) — exchange of grant_code
Introspection API — checking an existing pass_token

Quick Start