Authentication¶

Every protected endpoint of the API expects proof of identity in the request headers. It always relies on a credential obtained beforehand: a session (possibly an OpenID Connect token) or an API key.

One family of endpoints is deliberately outside all of this: the rail-station referential is open data attached to no group, and takes no credential at all.

Obtaining a session¶

1. Discover the group's provider¶

GET /api/v4/auth/provider?group_id=<group_id> tells you how a group authenticates: {"provider": "legacy"} for an email / password login, or {"provider": "auth0", "auth0": {"domain": "...", "connection": "..."}} when the group is delegated to an OpenID Connect provider.

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. Open the session¶

legacy group — POST /api/v4/login. An application/x-www-form-urlencoded body with email and password. The response returns {"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"]

auth0 group — OpenID Connect token. Obtain a JWT from the OpenID Connect provider returned by auth/provider, then use it as Authorization: Bearer <jwt>. Email / password login is rejected for these groups.

The session_id (or the JWT) is then used on protected requests, see the "Accepted mechanisms" section. GET /api/v4/logout closes the session (a 204 response):

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

Obtaining an API key¶

An API key is a persistent, revocable credential bound to a group and to a principal (a user, a device or a role). It avoids handling a password in an automated system.

Creating one goes through an API call authenticated by a session: you must first open a session (above) holding the admin role. POST /api/v4/groups/{group_id}/api-keys creates the key and returns it in the value field. The body declares exactly one principal: user_id, device_id or role (the latter together with group_ids); scopes and expire restrict it.

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"]

A group's keys are listed via GET /api/v4/groups/{group_id}/api-keys and deleted via DELETE /api/v4/groups/{group_id}/api-keys/{api_key_id}. A key spanning several groups, or a superuser key, is created via POST /api/v4/api-keys.

Accepted mechanisms¶

Authorization header¶

The mechanisms based on the Authorization header — session as bearer, API key and OpenID Connect token — are used identically: you place the exact header value in the request. In the example below, PYSAE_AUTH holds, depending on the case, Bearer <session_id>, Api-Key <api_key> or 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()

The API key also accepts the dedicated header x-api-key: <api_key>, equivalent to 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()

Machine-to-machine usage¶

For an automated integration:

• API key (recommended) — persistent, revocable, scoped by group and by role, with no password in the calling code.

The POST /api/v4/login flow targets human usage (the web interface) and is not recommended for automation.

Versioning (v2–v5, v4 by default) and the public / internal / datahub split are described on the home page.