Clés API

Gérez des clés API propres à une équipe, par programmation ou depuis le tableau de bord. Les clés s'authentifient via l'en-tête Authorization: Bearer.

Créer une clé

Génère une nouvelle clé pour une équipe et un environnement. La réponse inclut le secret en clair — enregistrez-le immédiatement, car il ne pourra plus être récupéré.

curl -X POST https://api.seeitlive.io/v1/keys \
  -H "Authorization: Bearer <dashboard-jwt>" \
  -H "Content-Type: application/json" \
  -d '{ "teamId": "<uuid>", "name": "Server key", "env": "live", "embedOrigins": ["https://acme.odoo.com"] }'

{
  "id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
  "name": "Server key",
  "env": "live",
  "prefix": "sil_live_ab12cd",
  "secret": "sil_live_ab12cdxxxxxxxxxxxxxxxxxxxxxxxx"
}

Lister les clés

Renvoie les clés actives (non révoquées) d'une équipe. Le secret n'est jamais inclus — seul le préfixe l'est, suffisant pour identifier une clé dans le tableau de bord ou les journaux.

[
  {
    "id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
    "name": "Server key",
    "env": "live",
    "prefix": "sil_live_ab12cd",
    "embedOrigins": ["https://acme.odoo.com"],
    "lastUsedAt": "2026-07-01T12:03:44.000Z",
    "createdAt": "2026-06-15T09:12:00.000Z"
  }
]

Mettre à jour une clé

Met à jour partiellement une clé. Seuls les champs fournis sont modifiés ; les champs omis restent inchangés.

curl -X PATCH https://api.seeitlive.io/v1/keys/d290f1ee-6c54-4b01-90e6-d701748f0851 \
  -H "Authorization: Bearer <dashboard-jwt>" \
  -H "Content-Type: application/json" \
  -d '{ "allowedIps": ["10.0.0.0/8 # office VPN"], "embedOrigins": ["https://acme.odoo.com # crm"], "expiresAt": "2026-12-31T00:00:00.000Z" }'

{
  "id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
  "name": "Server key",
  "env": "live",
  "prefix": "sil_live_ab12cd",
  "allowedIps": ["10.0.0.0/8 # office VPN"],
  "embedOrigins": ["https://acme.odoo.com # crm"],
  "expiresAt": "2026-12-31T00:00:00.000Z",
  "lastUsedAt": "2026-07-01T12:03:44.000Z",
  "createdAt": "2026-06-15T09:12:00.000Z"
}

Renouveler une clé

Émet un nouveau secret pour une clé existante et invalide l'ancien immédiatement. La clé conserve son identifiant, son nom, son environnement et ses réglages : listes d'autorisation, signature et TOTP survivent au renouvellement. Le secret en clair n'est affiché qu'une fois, exactement comme à la création.

{
  "id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
  "name": "Server key",
  "env": "live",
  "prefix": "sil_live_ef34gh",
  "secret": "sil_live_ef34ghxxxxxxxxxxxxxxxxxxxxxxxx"
}

Définir la clé par défaut

Marque une clé comme clé par défaut de l'équipe. Le tableau de bord l'utilise lorsqu'une session est créée depuis l'interface : ces sessions arrivent alors dans l'environnement de cette clé et lui sont attribuées. Définir une nouvelle clé par défaut annule la précédente ; une clé révoquée ne peut pas le devenir.

{ "ok": true }

Révoquer une clé

Désactive immédiatement une clé. Les requêtes en cours qui l'utilisent commencent aussitôt à échouer, et elle n'apparaît plus dans la réponse de liste.

{ "ok": true }

Signature des requêtes

La signature ajoute une vérification HMAC en plus de la clé porteuse. Consultez le contrat de signature dans le guide d'authentification pour savoir précisément comment calculer et envoyer la signature.

Activer la signature

Active la signature pour une clé et renvoie le secret de signature. Le secret n'est affiché qu'une seule fois — enregistrez-le immédiatement.

{ "signingSecret": "3fa1e2d0c9b84a5b8c9d0e1f2a3b4c5d6e7f8091a2b3c4d5e6f7081920a3b4c5" }

Faire tourner le secret de signature

Émet un nouveau secret de signature pour une clé, invalidant le précédent. Également affiché une seule fois.

{ "signingSecret": "8c9d0e1f2a3b4c5d6e7f8091a2b3c4d53fa1e2d0c9b84a5b6e7f8091920a3b4c" }

Désactiver la signature

Désactive la signature pour une clé. Les requêtes qui lui sont adressées n'ont plus besoin de signature.

{ "ok": true }

TOTP par clé

Un second facteur facultatif, propre à une clé : une fois activé, chaque requête faite avec elle doit aussi porter un code tournant valide dans un en-tête X-SeeItLive-Totp. Utile pour une clé détenue par une personne plutôt que par un serveur.

Activer

Renvoie la graine et une URL otpauth pour une application d'authentification. Les deux ne sont affichées qu'une fois — la graine n'est plus jamais lisible.

{
  "secret": "JBSWY3DPEHPK3PXP",
  "otpauthUrl": "otpauth://totp/SeeItLive:key%3Asil_live_ab12cd?secret=JBSWY3DPEHPK3PXP&issuer=SeeItLive"
}

Dès lors, les requêtes faites avec cette clé doivent inclure le code à 6 chiffres du moment ; sans lui, elles échouent avec un 401.

curl https://api.seeitlive.io/v1/sessions/<id>/status \
  -H "Authorization: Bearer sil_live_ab12cdxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "X-SeeItLive-Totp: 418205"

Désactiver

Désactive le second facteur et supprime la graine. Les requêtes faites avec la clé cessent d'exiger un code.

{ "ok": true }

Épinglage de certificat client (mTLS)

Épingle une clé à un certificat client unique. Une fois épinglée, une requête n'est acceptée que si votre point d'entrée transmet le certificat de l'appelant en PEM encodé pour URL dans un en-tête X-Ssl-Client-Cert et que son empreinte SHA-256 correspond à celle épinglée.

Épingler un certificat

Envoyez le certificat en PEM dans un champ pem. La réponse renvoie l'empreinte SHA-256 qui sera vérifiée.

curl -X POST https://api.seeitlive.io/v1/keys/d290f1ee-6c54-4b01-90e6-d701748f0851/cert/upload \
  -H "Authorization: Bearer <dashboard-jwt>" \
  -H "Content-Type: application/json" \
  -d "{ \"pem\": \"$(awk '{printf "%s\\n", $0}' client.crt)\" }"

{
  "fingerprint": "9f:86:d0:81:88:4c:7d:65:9a:2f:ea:a0:c5:5a:d0:15:a3:bf:4f:1b:2b:0b:82:2c:d1:5d:6c:15:b0:f0:0a:08"
}

Retirer l'épinglage

Supprime le certificat épinglé et cesse de l'exiger.

{ "ok": true }

Restrictions de fonctionnalités

Une équipe peut limiter ce que chaque clé peut faire, en deçà de ce que son forfait inclut. Trois fonctionnalités du forfait sont réglables par clé : sms, annotations et snapshot_history. Une clé hérite du défaut de l'équipe pour chaque fonctionnalité, sauf si elle le remplace. Nommer une fonctionnalité réglable que le forfait n'inclut pas renvoie 402 ; tout champ autre que ces trois fonctionnalités renvoie 400.

Défauts de l'équipe

Chaque champ est facultatif et accepte true ou false ; une fonctionnalité jamais réglée est activée. Nécessite la permission de gestion des clés.

Remplacements par clé

true ou false remplace le défaut de l'équipe ; null retire le remplacement pour que la clé en hérite de nouveau. effective indique ce qu'obtiennent les requêtes faites avec la clé. Nécessite la permission de gérer les clés, et la clé doit être active (non révoquée).

{ "sms": false, "annotations": null }

{
  "features": [
    { "key": "sms", "planAllows": true, "teamDefault": true, "override": false, "effective": false },
    { "key": "annotations", "planAllows": true, "teamDefault": false, "override": null, "effective": false },
    { "key": "snapshot_history", "planAllows": false, "teamDefault": true, "override": null, "effective": false }
  ]
}

Journal d'accès

Chaque tentative d'accès faite avec une clé est enregistrée — succès comme échecs — du plus récent au plus ancien. Sa lecture exige la permission de gestion des clés. Le journal ne contient aucun secret : ni la clé, ni le corps des requêtes.

{
  "items": [
    {
      "id": "f81d4fae-7dec-11d0-a765-00a0c91e6bf6",
      "outcome": "failure",
      "failureReason": "source_not_allowed",
      "ip": "203.0.113.7",
      "userAgent": "curl/8.5.0",
      "method": "POST",
      "path": "/api/v1/sessions",
      "createdAt": "2026-07-01T12:03:44.000Z"
    },
    {
      "id": "1f2a3b4c-5d6e-7f80-91a2-b3c4d5e6f708",
      "outcome": "success",
      "failureReason": null,
      "ip": "198.51.100.24",
      "userAgent": "@seeitlive/sdk 0.1.0",
      "method": "GET",
      "path": "/api/v1/sessions/abc/status",
      "createdAt": "2026-07-01T12:02:10.000Z"
    }
  ],
  "nextCursor": "eyJjcmVhdGVkQXQiOiIyMDI2LTA3LTAxVDEyOjAyOjEwLjAwMFoiLCJpZCI6IjFmMmEzYjRjIn0"
}

outcome vaut success ou failure. En cas d'échec, failureReason prend l'une des valeurs invalid_key, revoked, expired, source_not_allowed, totp, client_cert, signature, env_mismatch ou malformed.