# Authentication and scopes

https://gorally.games/en/developers/authentication

Every API call carries an organization key. The key identifies your organization: you never name it in a request.

## Send the key

Put the key in the `Authorization` header, preceded by `Bearer`:

```http
Authorization: Bearer rk_live_…
```

- Never in the URL or the query string: it would end up in logs.
- Never in code that runs in a browser: the API allows no CORS origin.
- A Rally session cookie opens nothing here.

**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()
```

With no key, or with an unknown, revoked or expired key, the API answers `401` with the `UNAUTHORIZED` code.

## Choose scopes

A key carries one or more scopes. Give it only the ones your software needs.

| Scope | What it allows |
|---|---|
| `read` | Read leagues, seasons, categories, standings, matches and events. |
| `write` | Everything `read` allows, plus creating a league or a season and writing a result. |
| `members:read` | Read rosters, the only part of the API that carries people’s names. |
| `members:write` | Everything `members:read` allows, plus adding a person to a roster. |

`write` gives no access to rosters. To read names, you need `members:read`, to be granted on purpose.

The API reference gives the scope of each operation. Without the right scope, the API answers `403` with the `FORBIDDEN` code.

## What a key never does

A key is not a person. No key, whatever its scopes, can:

- issue, rotate or revoke a key;
- create, change or revoke a webhook endpoint;
- give a role to a manager.

These actions happen in the Integrations screen, by someone who manages the organization.

## Rotate a key

Rotate a key when someone who knew it leaves your team, or on a regular schedule. Rally Leagues screens are in French: labels are quoted as they appear.

1. In the Integrations screen, find the key under “Clés d’API” (API keys).
2. Pick the rotation grace period: immediate cut-off, 24 hours, 3 days or at most 7 days.
3. Click “Faire tourner” (Rotate), followed by the key’s name.
4. Copy the new secret and deploy it to your server.

During the grace period, both the old and the new secret work. When it ends, the old one gets `401`.

## Revoke a key

Revoke a key when your software no longer needs it. Click “Révoquer” (Revoke), followed by the key’s name. The cut-off is immediate: the next call gets `401`.

If the secret leaked, revoke the key, or rotate it with an immediate cut-off.