API d'introspection

Vérifiez la validité d'un pass token et récupérez les attributs de vérification.

L'introspection est optionnelle. Depuis la v2.6.2, POST /v1/exchange retourne directement les attributs de vérification. L'introspection est utile pour re-vérifier un pass token existant dans un contexte différent (par exemple, lors d'une reconnexion utilisateur).

Endpoint

POST https://api.zykay.com/v1/introspect

Requête

Headers

Header	Requis	Description
`Content-Type`	Oui	`application/json`
`X-Partner-ID`	Oui	Votre Partner ID
`X-Partner-Timestamp`	Oui	Timestamp Unix en secondes
`X-Partner-Nonce`	Oui	UUID v4 unique par requête
`X-Partner-Signature`	Oui	Signature HMAC-SHA256 (base64url)

La signature HMAC se calcule de la même manière que pour l'API d'échange.

Body

{
  "pass_token": "p_xyz789abc123..."
}

Champ	Type	Requis	Description
`pass_token`	string	Oui	Pass token reçu lors de l'échange (commence par `p_`)

Réponse

Token actif (200)

{
  "active": true,
  "scope": "multi_scope_verification",
  "exp": 1739548800000,
  "iat": 1739534400000,
  "sub": "fid_abc123...",
  "attributes": {
    "age_over_18": true,
    "is_french": true,
    "nullifier": "0x7a3b9c...",
    "verification_method": "france_identite",
    "verified_at": 1739534400000
  },
  "scopes_verified": ["isAdult", "isFrench", "isUnique"],
  "proof_metadata": {
    "proof_count": 1,
    "total_generation_time_ms": 2500
  }
}

Champ	Type	Description
`active`	boolean	`true` si le token est valide et non expiré
`scope`	string	Type de vérification (`"age_verification"`, `"identity_verification"`, `"multi_scope_verification"`)
`exp`	number	Timestamp d'expiration (millisecondes)
`iat`	number	Timestamp de création (millisecondes)
`sub`	string	Identifiant du flux de vérification
`attributes`	object	Attributs de vérification (mêmes champs que la réponse d'échange)
`scopes_verified`	string[]	Liste des scopes vérifiés
`proof_metadata`	object	Métadonnées de la preuve (nombre de preuves, temps de génération)

Token inactif (200)

Un token expiré, invalide ou inconnu retourne un statut 200 avec active: false :

{
  "active": false
}

Conformément à la convention RFC 7662, un token invalide retourne un statut HTTP 200 (pas 401 ou 404). Vérifiez toujours le champ active dans la réponse.

Erreurs

Code	HTTP	Description
`INVALID_REQUEST`	400	`pass_token` manquant ou invalide
`INTERNAL_ERROR`	500	Erreur serveur

Les erreurs de signature HMAC (MISSING_HEADERS, INVALID_SIGNATURE, etc.) sont identiques à celles de l'API d'échange.

Exemples

const crypto = require('crypto');
 
function base64url(buffer) {
  return buffer.toString('base64')
    .replace(/\+/g, '-')
    .replace(/\//g, '_')
    .replace(/=+$/, '');
}
 
async function introspect(partnerId, partnerSecret, passToken) {
  const timestamp = Math.floor(Date.now() / 1000).toString();
  const nonce = crypto.randomUUID();
  const body = JSON.stringify({ pass_token: passToken });
 
  const bodyHash = base64url(
    crypto.createHash('sha256').update(body, 'utf8').digest()
  );
  const canonical = `${bodyHash}.${timestamp}.${partnerId}.${nonce}`;
  const secretBuffer = Buffer.from(partnerSecret, 'base64');
  const signature = base64url(
    crypto.createHmac('sha256', secretBuffer).update(canonical).digest()
  );
 
  const response = await fetch('https://api.zykay.com/v1/introspect', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-Partner-ID': partnerId,
      'X-Partner-Timestamp': timestamp,
      'X-Partner-Nonce': nonce,
      'X-Partner-Signature': signature
    },
    body
  });
 
  const data = await response.json();
 
  if (data.active) {
    console.log('Token valide, scopes:', data.scopes_verified);
    console.log('Attributs:', data.attributes);
  } else {
    console.log('Token expiré ou invalide');
  }
 
  return data;
}

🚫

Piège fréquent : Le Partner Secret est encodé en base64. Vous DEVEZ le décoder avant de l'utiliser comme clé HMAC. Consultez le guide de signature pour les détails.

Cas d'usage

Re-vérification de session : vérifier qu'un pass token stocké en session est toujours actif
Vérification côté backend : valider un pass token transmis par le frontend
Audit : consulter les métadonnées de la preuve (nombre de preuves, temps de génération)

Démarrage Rapide