# Authentification et scopes

https://gorally.games/developpeurs/authentification

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` :

```http
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**

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

**JavaScript**

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

**Python**

```python
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.

1. Dans l’écran Intégrations, trouve la clé dans « Clés d’API ».
2. Choisis la grâce de rotation : coupure immédiate, 24 heures, 3 jours ou 7 jours au plus.
3. Clique sur « Faire tourner », suivi du nom de la clé.
4. 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.