Référence API
Documentation complète de l'API ZYKAY.
URLs
| Service | URL |
|---|---|
| Widget (script tag) | https://widget-app.zykay.com/v4/loader.min.js |
| API Partner | https://api.zykay.com |
Endpoints
POST /v1/exchange
Échange un grant_code contre un pass_token et les résultats de vérification.
Exemple rapide :
curl -X POST https://api.zykay.com/v1/exchange \
-H "Content-Type: application/json" \
-H "X-Partner-ID: pk_live_xxx" \
-H "X-Partner-Timestamp: 1700000000" \
-H "X-Partner-Nonce: 550e8400-e29b-41d4-a716-446655440000" \
-H "X-Partner-Signature: IiqKqzxLThjE4anzR2UGycy5JrJKSjjD2m3R81RxsW8" \
-d '{"grant_code":"g_abc123..."}'Réponse :
{
"pass_token": "p_xyz789...",
"expires_in": 14400,
"age_over_18": true,
"scopes": ["isAdult"],
"attributes": {
"age_over_18": true
}
}POST /v1/introspect
Vérifie la validité d'un pass_token et retourne les attributs de vérification.
Exemple rapide :
curl -X POST https://api.zykay.com/v1/introspect \
-H "Content-Type: application/json" \
-H "X-Partner-ID: pk_live_xxx" \
-H "X-Partner-Timestamp: 1700000000" \
-H "X-Partner-Nonce: 550e8400-e29b-41d4-a716-446655440000" \
-H "X-Partner-Signature: ..." \
-d '{"pass_token":"p_xyz789..."}'Réponse :
{
"active": true,
"scope": "multi_scope_verification",
"attributes": {
"age_over_18": true,
"is_french": true
},
"scopes_verified": ["isAdult", "isFrench"]
}Authentification HMAC
Toutes les requêtes à l'API doivent être signées avec HMAC-SHA256.
Headers requis
| Header | Description |
|---|---|
X-Partner-ID | Votre Partner ID (pk_live_xxx) |
X-Partner-Timestamp | Timestamp Unix en secondes |
X-Partner-Nonce | UUID v4 unique par requête |
X-Partner-Signature | Signature HMAC-SHA256 (base64url) |
Génération de la signature
const crypto = require('crypto');
function base64url(buffer) {
return buffer.toString('base64')
.replace(/\+/g, '-')
.replace(/\//g, '_')
.replace(/=+$/, '');
}
// 1. Hash du body (SHA256)
const bodyHash = base64url(
crypto.createHash('sha256').update(JSON.stringify(body)).digest()
);
// 2. Chaîne canonique
const canonical = `${bodyHash}.${timestamp}.${partnerId}.${nonce}`;
// 3. IMPORTANT: Décoder le secret base64
const secretBytes = Buffer.from(partnerSecret, 'base64');
// 4. Signature HMAC
const signature = base64url(
crypto.createHmac('sha256', secretBytes).update(canonical).digest()
);⚠️
Le Partner Secret est encodé en base64. Vous DEVEZ le décoder avant de l'utiliser pour HMAC.
Scopes disponibles
| Scope | Type | Résultat | Portefeuille EUDI | |
|---|---|---|---|---|
isAdult | Binaire | age_over_18: true | Oui | Oui |
isFrench | Binaire | is_french: true | Oui | Oui |
isEU | Binaire | is_eu: true | Oui | Oui |
isMale | Binaire | is_male: true | Oui | Non |
isFemale | Binaire | is_female: true | Oui | Non |
isUnique | Nullifier | nullifier: "0x..." | Oui | Oui |
revealNationality | Disclosure | nationality: "FRA" | Oui | Non |
revealBirthYear | Disclosure | birth_year: 1990 | Oui | Non |
⚠️
isMale et isFemale sont mutuellement exclusifs. Les scopes marqués Non pour le Portefeuille EUDI ne sont pas disponibles avec data-client-proof-mode="true".
→ Référence complète des scopes
Codes d'erreur
| Code | HTTP | Description |
|---|---|---|
MISSING_HEADERS | 401 | Headers requis manquants |
INVALID_PARTNER | 403 | Partner ID non reconnu |
TIMESTAMP_SKEW | 401 | Timestamp décalé > 5 minutes |
INVALID_SIGNATURE | 401 | Signature HMAC incorrecte |
REPLAY_DETECTED | 401 | Nonce déjà utilisé |
INVALID_GRANT | 400 | Grant code invalide ou expiré |
→ Liste complète des codes d'erreur
Rate limits
Les limites publiées et la stratégie de retry sont documentées ici: