Docs / Sessions

Sessions

Référence de l’API sessions nouko : créer une session, lire son statut, lister avec pagination, annuler et obtenir la décision motivée.

Markdown OpenAPI

Une session représente une vérification d’identité pour un client. Elle possède un lien de collecte à usage unique et un cycle de vie.

Créer une session

POST /v1/sessions

En-tête Idempotency-Key obligatoire (120 caractères max.). Renvoyer la même clé renvoie la même session (200, replayed: true) avec un nouveau lien si l’ancien n’a pas été utilisé.

Champ	Type	Requis	Description
`reference`	string	Oui	Votre identifiant, 1 à 120 caractères
`country`	string	Oui	`BJ` ou `CI`
`tier`	integer	Non	Palier visé, 1 à 3 (défaut 2)
`redirect_url`	string	Non	URL HTTPS de retour, 500 caractères max.
`metadata`	object	Non	20 clés max., renvoyées dans chaque événement. Aucune donnée personnelle.
`expires_in`	integer	Non	Durée de validité en secondes, 900 à 2 592 000 (défaut 604 800, soit 7 jours)

curl -X POST https://nouko.openclouds.fr/api/public/v1/sessions \
  -H "Authorization: Bearer $NOUKO_API_KEY" \
  -H "Idempotency-Key: commande-001" \
  -H "Content-Type: application/json" \
  -d '{
    "reference": "client-42",
    "country": "BJ",
    "tier": 2,
    "redirect_url": "https://votre-site.com/kyc/retour",
    "metadata": { "user_id": "42" }
  }'

Réponse 201

HTTP/1.1 201 Created
X-Request-Id: 3b1e…

{
  "id": "6f1c2a9e-…",
  "reference": "client-42",
  "status": "draft",
  "country": "BJ",
  "tier": 2,
  "environment": "sandbox",
  "redirect_url": "https://votre-site.com/kyc/retour",
  "metadata": { "user_id": "42" },
  "expires_at": "2026-10-24T18:00:00.000Z",
  "verification_url": "https://nouko.openclouds.fr/verify/…",
  "replayed": false,
  "sandbox_scenario": null
}

Lire une session

GET /v1/sessions/{id}

curl https://nouko.openclouds.fr/api/public/v1/sessions/6f1c2a9e-… \
  -H "Authorization: Bearer $NOUKO_API_KEY"

Lister les sessions

GET /v1/sessions?status=&reference=&limit=&cursor=

Paramètre	Description
`status`	Filtre sur un statut
`reference`	Filtre sur votre référence
`limit`	1 à 100 (défaut 20)
`cursor`	Valeur `next_cursor` de la page précédente

La réponse contient data (les sessions, les plus récentes d’abord), has_more et next_cursor.

# Nécessite jq
cursor=""
while :; do
  page=$(curl -s "https://nouko.openclouds.fr/api/public/v1/sessions?limit=100&status=pending${cursor:+&cursor=$cursor}" \
    -H "Authorization: Bearer $NOUKO_API_KEY")
  echo "$page" | jq -r '.data[] | "\(.id) \(.reference)"'
  [ "$(echo "$page" | jq -r '.has_more')" = "true" ] || break
  cursor=$(echo "$page" | jq -r '.next_cursor')
done

Obtenir la décision

GET /v1/sessions/{id}/decision

Renvoie la décision, son motif et les contrôles effectués, sans aucune image. final vaut true quand la décision est définitive ; decision vaut approved, declined ou null.

curl https://nouko.openclouds.fr/api/public/v1/sessions/6f1c2a9e-…/decision \
  -H "Authorization: Bearer $NOUKO_API_KEY"

Réponse 200

{
  "id": "6f1c2a9e-…",
  "reference": "client-42",
  "status": "approved",
  "final": true,
  "decision": "approved",
  "tier": 2,
  "achieved_tier": 2,
  "reason": "Pièce lisible, visage concordant",
  "decided_at": "2026-10-17T18:12:00.000Z",
  "checks": [
    { "check_type": "document", "provider": "agent", "outcome": "pass", "risk": "low", "created_at": "…" }
  ]
}

Annuler une session

POST /v1/sessions/{id}/cancel

Possible uniquement pour une session draft ou complement ; le lien est désactivé. Une session déjà annulée renvoie 200. Sinon : 409 not_cancellable.

curl -X POST https://nouko.openclouds.fr/api/public/v1/sessions/6f1c2a9e-…/cancel \
  -H "Authorization: Bearer $NOUKO_API_KEY"

Statuts

Statut	Signification	Définitif
`draft`	Créée, en attente du client	Non
`pending`	Pièces soumises, examen en cours (automatique puis humain si besoin)	Non
`complement`	Pièces à refaire : le client peut reprendre son lien	Non
`approved`	Identité vérifiée	Oui
`rejected`	Vérification refusée (événement `session.declined`)	Oui
`expired`	Lien expiré avant soumission	Oui
`cancelled`	Annulée par vous	Oui