Authentification et scopes de l’API

Chaque appel à l’API porte une clé d’organisation. La clé désigne ton organisation : tu ne la nommes jamais dans une requête.

Envoyer la clé

Mets la clé dans l’en-tête Authorization, précédée de Bearer :

Authorization: Bearer rk_live_…

Jamais dans l’adresse ni dans la chaîne de requête : elle finirait dans des journaux.
Jamais dans du code qui tourne dans un navigateur : l’API n’autorise aucune origine CORS.
Un cookie de session Rally n’ouvre rien ici.

curl https://gorally.games/v1/leagues \
  -H "Authorization: Bearer $RALLY_API_KEY"

const response = await fetch('https://gorally.games/v1/leagues', {
  headers: {
    Authorization: `Bearer ${process.env.RALLY_API_KEY}`,
  },
});
const data = await response.json();

import os

import requests

response = requests.get(
    "https://gorally.games/v1/leagues",
    headers={"Authorization": f"Bearer {os.environ['RALLY_API_KEY']}"},
    timeout=10,
)
data = response.json()

Sans clé, ou avec une clé inconnue, révoquée ou expirée, l’API répond 401 avec le code UNAUTHORIZED.

Choisir les scopes

Une clé porte un ou plusieurs scopes. Donne-lui seulement ceux dont ton logiciel a besoin.

Scope	Ce qu’il permet
`read`	Lire les ligues, les saisons, les catégories, les classements, les rencontres et les événements.
`write`	Tout ce que permet `read`, plus créer une ligue ou une saison et écrire un résultat.
`members:read`	Lire les effectifs, la seule partie de l’API qui porte des noms de personnes.
`members:write`	Tout ce que permet `members:read`, plus ajouter une personne à un effectif.

write ne donne aucun accès aux effectifs. Pour lire des noms, il faut members:read, à accorder en le voulant.

La référence de l’API donne le scope de chaque opération. Sans le bon scope, l’API répond 403 avec le code FORBIDDEN.

Ce qu’une clé ne fait jamais

Une clé n’est pas une personne. Aucune clé, quels que soient ses scopes, ne peut :

émettre, faire tourner ou révoquer une clé ;
déclarer, modifier ou révoquer un point de livraison de webhooks ;
confier un rôle à un responsable.

Ces gestes se font dans l’écran Intégrations, par une personne qui gère l’organisation.

Faire tourner une clé

Fais tourner une clé quand quelqu’un qui la connaissait quitte ton équipe, ou à intervalle régulier.

Dans l’écran Intégrations, trouve la clé dans « Clés d’API ».
Choisis la grâce de rotation : coupure immédiate, 24 heures, 3 jours ou 7 jours au plus.
Clique sur « Faire tourner », suivi du nom de la clé.
Copie le nouveau secret et déploie-le sur ton serveur.

Pendant la grâce, l’ancien et le nouveau secret fonctionnent tous les deux. À l’échéance, l’ancien reçoit 401.

Révoquer une clé

Révoque une clé quand ton logiciel n’en a plus besoin. Clique sur « Révoquer », suivi du nom de la clé. La coupure est immédiate : l’appel suivant reçoit 401.

Si le secret a fuité, révoque la clé, ou fais-la tourner avec une coupure immédiate.

Guide suivant : Webhooks →