API Billing Session

Émet un token de session signé pour le rail ADULT_BLIND. Réservé aux partenaires sur ce rail de conformité.

Cet endpoint est uniquement disponible pour les organisations configurées sur le rail ADULT_BLIND. Contactez tech@zykay.com pour activer ce mode.

Endpoint

POST https://app.zykay.com/api/billing/session

Authentification

Même signature HMAC que POST /v1/exchange — headers identiques :

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	Identifiant unique par requête (hex 32 chars recommandé)
`x-partner-signature`	Oui	Signature HMAC-SHA256 (base64url)

La chaîne canonique et le calcul de signature sont identiques à ceux décrits dans API d'échange de Grant.

Corps de la requête

{
  "scopes": ["isAdult"],
  "origin": "https://votresite.com"
}

Champ	Type	Requis	Description
`origin`	string	Oui	URL d'origine de votre site (doit correspondre à votre domaine enregistré)
`scopes`	string[]	Non	Scopes demandés. Défaut : `["isAdult"]`. Disponible : `isAdult`, `isFrench`, `isEU`, `isUnique`

Réponse (201 Created)

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_in": 300
}

Champ	Type	Description
`token`	string	Token signé (JWS). À transmettre au widget via `data-session-token`
`expires_in`	integer	Durée de validité en secondes (toujours `300` = 5 minutes)

⚠️

Le token expire après 5 minutes. Appelez cet endpoint à chaque chargement de page — ne mettez pas le token en cache entre les requêtes.

Codes d'erreur

Code	HTTP	Description	Solution
`UNAUTHORIZED` / `INVALID_PARTNER`	401/403	Signature HMAC invalide ou Partner ID inconnu	Vérifiez vos identifiants et le calcul de signature
`FORBIDDEN_RAIL`	403	L'organisation n'est pas sur le rail ADULT_BLIND	Contactez tech@zykay.com pour activer le rail
`MISSING_BLIND_APP_ID`	400	`blindAppId` non configuré pour l'organisation	Contactez le support ZYKAY
`MISSING_ORIGIN`	400	Le champ `origin` est absent du corps	Incluez `"origin": "https://votresite.com"`
`INVALID_SCOPES`	400	Scopes non supportés pour votre tier	Vérifiez les scopes disponibles pour votre niveau
`INTERNAL_ERROR`	500	Erreur serveur	Réessayez avec backoff exponentiel

Limites de débit

Phase	Limite	Fenêtre	Clé
Pré-auth (IP)	30 req	60s	IP client
Post-auth (par partenaire)	100 req	60s	Partner ID

La limite pré-auth protège contre les abus avant la vérification HMAC. La limite post-auth (100/min) est conçue pour le trafic serveur-à-serveur normal.

Clés publiques d'attestation (JWKS)

Pour vérifier les signatures d'attestation côté serveur sans appel API :

GET https://app.zykay.com/api/billing/attestation-keys

Réponse :

{
  "keys": [
    {
      "kty": "OKP",
      "crv": "Ed25519",
      "kid": "ak-2026-02",
      "x": "...",
      "use": "sig"
    }
  ]
}

Mettez en cache la réponse JWKS jusqu'à 1 heure. Les clés tournent rarement (tous les quelques mois). En cas de changement de clé, ZYKAY vous en informe à l'avance.

Structure du payload d'attestation

Une fois le JWS décodé et la signature vérifiée :

{
  "jti": "abc123...",
  "exp": 1708560000,
  "scope_mask": 1,
  "app_id": "blind_app_xxx",
  "origin_hash": "sha256_of_origin",
  "nullifier": "0x7a3b9c...",
  "aud": "zykay-verifier",
  "ver": "1.0"
}

Champ	Description
`scope_mask`	Bitmask des scopes vérifiés. Bit 0 = `isAdult`, bit 1 = `isFrench`, bit 2 = `isEU`, bit 3 = `isUnique`
`nullifier`	Identifiant unique respectant la vie privée (spécifique à votre `app_id`)
`exp`	Expiration Unix — vérifiez que `exp > now()`

Exemple complet

Voir le guide d'intégration complet : Sites Adultes (ADULT_BLIND)

Démarrage Rapide