Sessions et révocation

Une session représente une connexion active à votre espace de travail Coffrify, ouverte depuis un navigateur ou un appareil donné. Les endpoints Sessions vous permettent d'auditer ces connexions, d'inspecter la session courante et de couper l'accès à distance quand un appareil est perdu, volé ou simplement oublié sur un poste public. Toutes les routes vivent sous https://api.coffrify.com/v1 et s'authentifient avec un en-tête Authorization: Bearer <clé>. La lecture exige le scope sessions:read, la révocation le scope sessions:manage.

Scopes requis

Lister les sessions actives

GET /v1/sessions renvoie les sessions actives (non révoquées) du compte propriétaire de l'espace de travail, triées par dernière activité décroissante. La réponse est une liste standard Coffrify avec object: "list" et un tableau data. Chaque session expose son appareil, son contexte réseau et le statut de vérification renforcée.

import { Coffrify } from '@coffrify/sdk';
 
const coffrify = new Coffrify({ apiKey: process.env.COFFRIFY_API_KEY });
 
const { data } = await coffrify.sessions.list();
for (const s of data) {
  console.log(s.device_name, s.os, s.browser, s.ip_address, s.last_active_at);
}

Chaque entrée contient notamment id, device_name, device_type, os, browser, ip_address, country_code, city, created_at et last_active_at. Les champs mfa_verified et mfa_verified_at indiquent si la session a passé une vérification renforcée, ce qui aide à repérer une connexion à privilégier ou, au contraire, à couper.

{
  "object": "list",
  "data": [
    {
      "id": "ses_3aK9",
      "device_name": "MacBook Pro",
      "device_type": "desktop",
      "os": "macOS 15",
      "browser": "Safari",
      "ip_address": "185.12.x.x",
      "country_code": "FR",
      "city": "Paris",
      "mfa_verified": true,
      "mfa_verified_at": "2026-06-10T08:14:00Z",
      "created_at": "2026-06-08T09:00:00Z",
      "last_active_at": "2026-06-10T08:40:00Z"
    }
  ]
}

Inspecter la session courante

GET /v1/sessions/current renvoie le contexte de la session qui exécute l'appel : created_at, last_active_at, ip_address, user_agent et l'indicateur géographique country_code. La réponse porte toujours is_current: true et un champ kind. Appelée avec une clé API plutôt qu'une session de navigateur, la route renvoie un contexte synthétique avec kind: "api_key", sans ligne de session réelle.

const me = await coffrify.sessions.current();
console.log(me.kind, me.ip_address, me.last_active_at);

Révoquer une session précise

DELETE /v1/sessions/{id} coupe immédiatement une session identifiée par son id. La réponse confirme l'opération avec revoked: true. Si l'identifiant est inconnu ou si la session était déjà révoquée, l'API renvoie une erreur not_found (HTTP 404), ce qui rend l'appel sûr à réessayer. Cette route est une écriture : ajoutez un en-tête Idempotency-Key (entre 8 et 255 caractères) pour vous prémunir des doublons lors d'un rejeu réseau.

const res = await coffrify.sessions.revoke('ses_3aK9');
console.log(res.revoked); // true

Se déconnecter partout ailleurs

POST /v1/sessions/revoke-all révoque toutes les sessions sauf celle qui émet la requête, idéal pour un bouton « Se déconnecter de tous les autres appareils ». La réponse renvoie revoked (le nombre de sessions coupées) et kept_current: true. Comme l'appel doit identifier la session à conserver, il requiert une session utilisateur : invoqué avec une simple clé API, sans session, il répond par une erreur HTTP 401.

const res = await coffrify.sessions.revokeAll();
console.log(`${res.revoked} session(s) coupée(s)`);
console.log(res.kept_current); // true

Cas d'usage : couper l'accès d'un appareil perdu

Le scénario de sécurité le plus courant consiste à révoquer à distance la session d'un appareil égaré. Listez d'abord les sessions, repérez celle qui correspond (par device_name, country_code ou ip_address), puis révoquez-la. En cas de doute sur le poste compromis, déconnectez tout sauf la session de confiance avec revoke-all.

// 1. Repérer la session suspecte
const { data } = await coffrify.sessions.list();
const suspecte = data.find(s => s.city === 'Marseille' && !s.mfa_verified);
 
// 2. La couper
if (suspecte) {
  await coffrify.sessions.revoke(suspecte.id);
}
 
// 3. Doute total : tout couper sauf l'appareil courant
await coffrify.sessions.revokeAll();

Évènements webhook

Deux évènements vous permettent de réagir aux mouvements de session sans interrogation périodique. Abonnez un endpoint webhook pour les recevoir en temps réel et alimenter votre journal de sécurité ou déclencher une alerte.