Authentification

Votre serveur s’authentifie avec une clé API. Une page web n’a jamais de clé : votre serveur lui fournit un stream token temporaire pour ouvrir le stream.

Clés API

Créez vos clés dans votre espace compte. Une clé ne s’affiche qu’une fois, à sa création : copiez-la immédiatement. Nous n’en gardons aucune copie lisible : une clé perdue ne se retrouve pas, elle se remplace.

Une clé de test a toujours les droits de la Sandbox, quelle que soit votre offre. Différé mis à part, elle se comporte exactement comme une clé live : mêmes messages, mêmes cursors, mêmes réponses.

Envoyez la clé dans le header Authorization, sur chaque requête REST comme à l’ouverture du WebSocket :

curl https://api.fathomcharts.com/v1/usage -H "Authorization: Bearer $FATHOM_CHARTS_API_KEY"

Une clé invalide, expirée ou révoquée est refusée avec 401 UNAUTHORIZED en REST ; sur le WebSocket, la connexion est fermée avec le close code 4001. Une clé valide qui n’a pas le scope demandé est refusée avec 403 FORBIDDEN, ou le close code 4003 sur le WebSocket.

Scopes et restrictions

Une clé ne donne accès qu’aux scopes que vous lui accordez. Si elle fuite, les dégâts restent limités : une clé qui ne sert qu’à lire le stream n’a pas besoin de lancer des exports.

Vous pouvez aussi restreindre une clé à certains instruments ou à certaines adresses IP, et lui fixer une date d’expiration. Par l’API, avec une clé qui a le scope keys :

curl https://api.fathomcharts.com/v1/keys \
  -H "Authorization: Bearer $FATHOM_CHARTS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"collecteur","environment":"live","scopes":["stream","history"],"instruments":["NQ.front"],"allowedIps":["203.0.113.0/24"]}'

La réponse contient la clé complète dans le champ key, une seule fois, et son identifiant dans id. Une clé ne peut pas créer de clé avec plus de scopes qu’elle, ni une clé de l’autre type (test ou live). GET /v1/keys liste vos clés.

Un compte a au plus 10 clés actives. Toutes vos clés partagent les mêmes limites : en créer davantage n’augmente pas vos quotas.

Rotation d’une clé

Pour changer de clé sans interrompre votre service, faites une rotation (<id> : le champ id de la clé, donné par GET /v1/keys) :

curl -X POST https://api.fathomcharts.com/v1/keys/<id>/rotate \
  -H "Authorization: Bearer $FATHOM_CHARTS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"gracePeriodSeconds":172800}'

Vous recevez une nouvelle clé, avec les mêmes scopes et les mêmes restrictions. L’ancienne reste valable pendant la grace period (gracePeriodSeconds, 7 jours au plus ; ici 2 jours), le temps de déployer la nouvelle partout, puis elle est révoquée. Avec 0, elle est révoquée immédiatement. Une clé ne passe qu’une fois en rotation : une seconde rotation est refusée avec 409 CONFLICT.

Révoquer une clé

DELETE /v1/keys/<id>, ou depuis l’espace compte. La révocation est immédiate : les connexions WebSocket ouvertes avec cette clé sont fermées dans la seconde (close code 4003).

Accès depuis un navigateur

Une clé API ne doit jamais apparaître dans une page web : n’importe quel visiteur pourrait la lire. Pour afficher le stream dans un navigateur :

1. votre serveur demande un stream token avec sa clé ;
2. il le transmet à la page ;
3. la page ouvre le WebSocket et envoie ce token.

Côté serveur :

curl -X POST https://api.fathomcharts.com/v1/stream-tokens -H "Authorization: Bearer $FATHOM_CHARTS_API_KEY"

La réponse contient le token (token) et son expiration (expiresAt). Avec le SDK : FathomChartsRest.streamToken().

Côté page, donnez au SDK une fonction qui récupère un token auprès de votre serveur (ici une route /api/fathom-charts-token de votre backend, qui fait l’appel ci-dessus). Le SDK l’appelle à chaque connexion et s’occupe du reste :

import { FathomChartsStream } from '@fathom-charts/sdk';

const stream = new FathomChartsStream({
  url: 'wss://stream.fathomcharts.com/v1',
  streamToken: async () => {
    const response = await fetch('/api/fathom-charts-token', { method: 'POST' });
    const { token } = (await response.json()) as { token: string };
    return token;
  },
});

for await (const event of stream.subscribe({ instrument: 'NQ.front', indicator: 'big-trades', params: { minimum: 30 } })) {
  console.log(event.type, event);
}

Sans SDK, envoyez le token dans un message auth, en tout premier, dans les 5 secondes qui suivent l’ouverture :

const { token } = (await fetch('/api/fathom-charts-token', { method: 'POST' }).then((r) => r.json())) as { token: string };
const ws = new WebSocket('wss://stream.fathomcharts.com/v1');
ws.onopen = () => {
  ws.send(JSON.stringify({ t: 'auth', token }));
  ws.send(JSON.stringify({
    t: 'subscribe', sub: 'bt', instrument: 'NQ.front', indicator: 'big-trades',
    params: { minimum: 30 }, mode: 'live', from: 'live',
  }));
};
ws.onmessage = (e) => console.log(JSON.parse(e.data));

À savoir :

• un stream token est valable 60 secondes et ne sert qu’une fois. Il ouvre la connexion, qui reste ensuite ouverte aussi longtemps que nécessaire. Chaque reconnexion demande un nouveau token ;
• le token a les mêmes droits et les mêmes limites que la clé qui l’a créé, et cesse de fonctionner si elle est révoquée ;
• n’importe quel site peut utiliser un token : ne le fournissez qu’à vos propres utilisateurs, une fois authentifiés.

Si le premier message n’est pas un auth valide, ou s’il n’arrive pas dans les 5 secondes, la connexion est fermée avec le close code 4001.

Connexion au portail

L’espace compte (clés, offres, facturation, consommation) n’a pas de mot de passe. Sur la page Connexion, saisissez votre adresse e-mail : vous recevez un lien de connexion valable 15 minutes, utilisable une seule fois. Vous pouvez demander jusqu’à 5 liens par heure.

Lien refusé ? Il a expiré ou a déjà servi : demandez-en un nouveau. Une fois connecté, votre session reste ouverte 30 jours sur ce navigateur.