Authentification¶

Tous les endpoints protégés de l'API attendent une preuve d'identité dans l'en-tête de la requête. Elle repose toujours sur un identifiant obtenu au préalable : une session (éventuellement un jeton OpenID Connect) ou une clé d'API.

Une famille d'endpoints reste volontairement hors de tout cela : le référentiel des gares ferroviaires est une donnée ouverte rattachée à aucun groupe, et n'attend aucun identifiant.

Obtenir une session¶

1. Découvrir le provider du groupe¶

GET /api/v4/auth/provider?group_id=<group_id> indique comment un groupe s'authentifie : {"provider": "legacy"} pour un login e-mail / mot de passe, ou {"provider": "auth0", "auth0": {"domain": "...", "connection": "..."}} lorsque le groupe est délégué à un provider OpenID Connect.

import os

import httpx

group_id = os.environ["GROUP_ID"]

response = httpx.get(
    "https://api.pysae.com/api/v4/auth/provider",
    params={"group_id": group_id},
)
response.raise_for_status()

# {"provider": "legacy"} or {"provider": "auth0", "auth0": {"domain": ...}}
print(response.json())

2. Ouvrir la session¶

Groupe legacy — POST /api/v4/login. Corps application/x-www-form-urlencoded avec email et password. La réponse renvoie {"session_id": "...", "expires_days": ...}.

import os

import httpx

email = os.environ["EMAIL"]
password = os.environ["PASSWORD"]

response = httpx.post(
    "https://api.pysae.com/api/v4/login",
    data={"email": email, "password": password},
)
response.raise_for_status()

session_id = response.json()["session_id"]

Groupe auth0 — jeton OpenID Connect. Obtenir un JWT auprès du provider OpenID Connect renvoyé par auth/provider, puis l'utiliser en Authorization: Bearer <jwt>. Le login e-mail / mot de passe est refusé pour ces groupes.

Le session_id (ou le JWT) obtenu s'emploie ensuite dans les requêtes protégées, cf. la section « Mécanismes acceptés ». GET /api/v4/logout ferme la session (réponse 204) :

curl --request GET \
  --header "Authorization: Bearer <session_id>" \
  "https://api.pysae.com/api/v4/logout"

Obtenir une clé d'API¶

Une clé d'API est un identifiant persistant et révocable, lié à un groupe et à un principal (un utilisateur, un appareil ou un rôle). Elle évite de manipuler un mot de passe dans un système automatisé.

Sa création passe par un appel API authentifié par une session : il faut donc d'abord ouvrir une session (ci-dessus) disposant du rôle admin. POST /api/v4/groups/{group_id}/api-keys crée la clé et la renvoie dans le champ value. Le corps déclare exactement un principal : user_id, device_id ou role (ce dernier accompagné de group_ids) ; scopes et expire permettent de la restreindre.

import os

import httpx

group_id = os.environ["GROUP_ID"]
session_id = os.environ["SESSION_ID"]
user_id = os.environ["USER_ID"]

response = httpx.post(
    f"https://api.pysae.com/api/v4/groups/{group_id}/api-keys",
    headers={"Authorization": f"Bearer {session_id}"},
    json={"user_id": user_id},
)
response.raise_for_status()

api_key = response.json()["value"]

Les clés d'un groupe se listent via GET /api/v4/groups/{group_id}/api-keys et se suppriment via DELETE /api/v4/groups/{group_id}/api-keys/{api_key_id}. Une clé couvrant plusieurs groupes, ou une clé superuser, se crée via POST /api/v4/api-keys.

Mécanismes acceptés¶

En-tête Authorization¶

Les mécanismes fondés sur l'en-tête Authorization — session en bearer, clé d'API et jeton OpenID Connect — s'emploient de façon identique : on place la valeur exacte de l'en-tête dans la requête. Dans l'exemple ci-dessous, PYSAE_AUTH vaut selon le cas Bearer <session_id>, Api-Key <api_key> ou Bearer <jwt>.

import os

import httpx

group_id = os.environ["GROUP_ID"]
authorization = os.environ["PYSAE_AUTH"]

response = httpx.get(
    f"https://api.pysae.com/api/v4/groups/{group_id}/export/trips",
    headers={"Authorization": authorization},
    params={"date": "20260131"},
    timeout=None,
)
response.raise_for_status()

La clé d'API accepte aussi l'en-tête dédié x-api-key: <api_key>, équivalent à Authorization: Api-Key <api_key> :

import os

import httpx

group_id = os.environ["GROUP_ID"]
api_key = os.environ["PYSAE_API_KEY"]

response = httpx.get(
    f"https://api.pysae.com/api/v4/groups/{group_id}/export/trips",
    headers={"x-api-key": api_key},
    params={"date": "20260131"},
    timeout=None,
)
response.raise_for_status()

Usage machine-à-machine¶

Pour une intégration automatisée :

• Clé d'API (recommandé) — persistante, révocable, scopée par groupe et par rôle, sans mot de passe dans le code appelant.

Le parcours POST /api/v4/login vise l'usage humain (interface web) et n'est pas recommandé pour l'automatisation.

Le versionnement (v2–v5, v4 par défaut) et le découpage public / internal / datahub sont décrits sur la page d'accueil.