Scopes disponibles

Référence complète des scopes de vérification ZYKAY.

Qu'est-ce qu'un scope ?

Un scope définit quelle information d'identité vous souhaitez vérifier. Les scopes sont spécifiés via l'attribut data-scopes du widget et déterminent les attributs retournés dans la réponse de l'API d'échange.

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

Tableau des scopes

Scope	Type	Description	Attribut retourné	PDF	Portefeuille EUDI
`isAdult`	Binaire	A 18 ans ou plus	`age_over_18: true`	Oui	Oui
`isFrench`	Binaire	Nationalité française	`is_french: true`	Oui	Oui
`isEU`	Binaire	Citoyen de l'Union européenne	`is_eu: true`	Oui	Oui
`isMale`	Binaire	Sexe masculin	`is_male: true`	Oui	Non
`isFemale`	Binaire	Sexe féminin	`is_female: true`	Oui	Non
`isUnique`	Nullifier	Identifiant unique par application	`nullifier: "0x..."`	Oui	Oui
`revealNationality`	Divulgation	Code nationalité ISO 3166-1 alpha-3	`nationality: "FRA"`	Oui	Non
`revealBirthYear`	Divulgation	Année de naissance	`birth_year: 1990`	Oui	Non

🚫

Les scopes isMale, isFemale, revealNationality et revealBirthYear ne sont pas disponibles avec le Portefeuille EUDI. Si vous les incluez dans data-scopes avec data-client-proof-mode="true", la vérification échouera.

⚠️

Les scopes isMale et isFemale sont mutuellement exclusifs. Vous ne pouvez pas demander les deux en même temps.

Scopes binaires

Les scopes binaires retournent true ou false. Ce sont les plus courants :

isAdult — vérifie que l'utilisateur a 18 ans ou plus. Scope par défaut si data-scopes n'est pas spécifié.
isFrench — vérifie que la nationalité est française (code ISO 250).
isEU — vérifie que la nationalité est celle d'un des 27 États membres de l'Union européenne.
isMale / isFemale — vérifie le sexe. Uniquement disponible avec la vérification PDF.

Scope `isUnique` (résistance Sybil)

Le scope isUnique génère un identifiant cryptographique (nullifier) qui est :

Unique par application : deux sites partenaires différents produisent des nullifiers différents pour le même utilisateur
Unique par utilisateur : deux utilisateurs différents produisent des nullifiers différents
Déterministe : le même utilisateur sur le même site produit toujours le même nullifier

Cela permet de détecter les doublons (attaques Sybil) sans révéler l'identité de l'utilisateur.

Le scope isUnique nécessite un app_id qui est automatiquement dérivé de votre Partner ID. Aucune configuration supplémentaire n'est requise.

Scopes de divulgation

Les scopes de divulgation retournent une valeur concrète (pas un booléen). Ils sont uniquement disponibles avec la vérification PDF :

revealNationality — retourne le code nationalité ISO 3166-1 alpha-3 (ex: "FRA", "DEU", "ITA")
revealBirthYear — retourne l'année de naissance (ex: 1990)

Exemples de combinaisons

<!-- Vérification d'âge uniquement (scope par défaut) -->
data-scopes="isAdult"
 
<!-- Âge + nationalité française -->
data-scopes="isAdult,isFrench"
 
<!-- Âge + nationalité + résistance Sybil (recommandé Portefeuille EUDI) -->
data-scopes="isAdult,isFrench,isUnique"
 
<!-- Citoyen UE + résistance Sybil -->
data-scopes="isEU,isUnique"
 
<!-- Âge + sexe (PDF uniquement) -->
data-scopes="isAdult,isMale"

Réponse API selon les scopes

Exemples de réponses POST /v1/exchange pour différentes combinaisons de scopes :

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

Prochaines étapes

Intégration Frontend — configuration du widget et des attributs
Backend (Exchange API) — échange du grant_code
API d'introspection — vérification d'un pass token existant

Démarrage Rapide