Autenticación¶
Todos los endpoints protegidos de la API esperan una prueba de identidad en la cabecera de la solicitud. Esta se basa siempre en una credencial obtenida previamente: una sesión (eventualmente un token OpenID Connect) o una clave de API.
Una familia de endpoints queda deliberadamente al margen de todo esto: el referencial de estaciones ferroviarias es un dato abierto que no está vinculado a ningún grupo y no requiere ninguna credencial.
Obtener una sesión¶
1. Descubrir el proveedor del grupo¶
GET /api/v4/auth/provider?group_id=<group_id> indica cómo se autentica un grupo: {"provider": "legacy"} para un inicio de sesión con correo electrónico / contraseña, o {"provider": "auth0", "auth0": {"domain": "...", "connection": "..."}} cuando el grupo está delegado en un proveedor 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. Abrir la sesión¶
Grupo legacy — POST /api/v4/login. Cuerpo application/x-www-form-urlencoded con email y password. La respuesta devuelve {"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"]
Grupo auth0 — token OpenID Connect. Obtenga un JWT del proveedor OpenID Connect devuelto por auth/provider y utilícelo como Authorization: Bearer <jwt>. El inicio de sesión con correo electrónico / contraseña se rechaza para estos grupos.
El session_id (o el JWT) obtenido se utiliza después en las solicitudes protegidas; consulte la sección «Mecanismos aceptados». GET /api/v4/logout cierra la sesión (respuesta 204):
curl --request GET \
--header "Authorization: Bearer <session_id>" \
"https://api.pysae.com/api/v4/logout"
Una sesión también deja de ser válida en cuanto se elimina la cuenta de usuario a la que pertenece: sus sesiones se revocan con ella, sin esperar a su fecha de caducidad.
Las antiguas rutas de cierre de sesión GET /api/v2/logout y GET /auth/logout aceptan respectivamente next y redirect para volver a una página local. Un destino externo se sustituye por /.
Obtener una clave de API¶
Una clave de API es una credencial persistente y revocable, vinculada a un grupo y a un principal (un usuario, un dispositivo o un rol). Evita manipular una contraseña en un sistema automatizado.
Su creación pasa por una llamada a la API autenticada mediante una sesión: por tanto, primero debe abrirse una sesión (véase más arriba) que disponga del rol admin. POST /api/v4/groups/{group_id}/api-keys crea la clave y la devuelve en el campo value. El cuerpo declara exactamente un principal: user_id, device_id o role (este último acompañado de group_ids); expire limita su periodo de validez. Asígnele un label (de 1 a 100 caracteres) que nombre la integración que la poseerá.
No utilice scopes. Este campo restringe la clave a las pocas rutas que declaran un alcance correspondiente y está pensado para las credenciales de servicio internas; una clave con un alcance que ninguna ruta declara se rechaza al crearla, y un alcance no relacionado no da acceso a nada. Sin él, la clave alcanza todo lo que su rol autoriza.
La clave solo se comunica una vez
El campo value solo aparece en la respuesta a esta creación: guárdelo en cuanto lo reciba. La API solo conserva una huella, y ningún otro endpoint lo devuelve. Una clave extraviada no se puede recuperar: se revoca y se vuelve a crear.
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"]
Las claves de un grupo se listan mediante GET /api/v4/groups/{group_id}/api-keys y se eliminan mediante DELETE /api/v4/groups/{group_id}/api-keys/{api_key_id}. Una clave que abarque varios grupos, o una clave superuser, se crea mediante POST /api/v4/api-keys. Con all_groups: true y role: "reader" (sin group_ids), un superuser crea una clave de solo lectura sobre todos los grupos no archivados, incluidos los creados después de ella: la lista de grupos se vuelve a leer en cada llamada, mientras que la de una clave con group_ids queda fijada en el momento de su creación. También lee los datos de todos los equipos de esos grupos, mientras que una clave con group_ids, que no lleva ningún equipo, conserva su perímetro: los datos no vinculados a ningún equipo o vinculados a un equipo archivado. Una clave no vinculada a ningún grupo (clave superuser, clave all_groups, o clave user_id o device_id creada ahí, que nunca lleva grupo) no aparece en la lista de ningún grupo: un superuser la lista mediante GET /api/v4/api-keys y la elimina mediante DELETE /api/v4/api-keys/{api_key_id}.
Estos endpoints de lectura no devuelven value sino value_masked: los cuatro primeros caracteres del secreto, *** y luego los cuatro últimos (cD5D***Ifi8). Lo suficiente para reconocer, antes de revocarla, la clave que utiliza una integración determinada.
También devuelven su label, created_by (el usuario que la creó), created_at y last_used_at: la fecha de la última llamada autenticada por la clave, con precisión de minutos, vacía mientras no se haya utilizado nunca. Así se sabe si una integración sigue utilizando una clave, o ha pasado a una nueva, antes de revocar la antigua.
Una clave se renombra mediante PATCH /api/v4/groups/{group_id}/api-keys/{api_key_id}, cuyo cuerpo lleva el nuevo label y nada más: el secreto, el principal y la caducidad no cambian, y la integración que posee la clave sigue autenticándose.
Claves de su propia cuenta¶
Un integrador que trabaja para varios grupos gestiona sus claves sin ser administrador de ninguno de ellos, mediante /api/v4/users/me/api-keys. Una clave de este tipo actúa en nombre de su cuenta: cada llamada que autentica lleva sus roles, restricciones de equipos incluidas, y nada más. Un administrador de grupo que retire su rol en su grupo corta inmediatamente todas sus claves de ese grupo.
POST /api/v4/users/me/api-keyscrea una. El cuerpo aceptagroup_ids,label,expireyscopes; se rechaza cualquier campo que designe un principal (user_id,role,superuser,device_id). Congroup_ids, que contiene un grupo en el que su cuenta tiene un rol, la clave solo alcanza ese grupo y aparece en su lista de claves, donde sus administradores la ven y pueden revocarla. Una clave cubre como máximo un grupo, para que los administradores de un cliente no sepan nada de sus otros clientes ni puedan cortarlos: cree una clave por grupo. Singroup_ids, alcanza todos los grupos en los que su cuenta tiene un rol. La creación exige una sesión abierta por una persona, no una clave de API, y una cuenta superuser no puede utilizar esta ruta. Una cuenta posee como máximo 5 claves activas por grupo, y 5 no vinculadas a ningún grupo, contando las que un administrador de grupo haya creado en su nombre. El secreto se devuelve una sola vez, envalue.GET /api/v4/users/me/api-keyslista las claves que actúan en nombre de su cuenta, sin su secreto.PATCH /api/v4/users/me/api-keys/{api_key_id}renombra una,DELETE /api/v4/users/me/api-keys/{api_key_id}la revoca; una clave puede revocarse a sí misma. Una clave que no es suya responde 404.
Una clave user_id creada en un grupo, por su administrador o por usted, solo alcanza ese grupo, aunque la cuenta tenga roles en otros grupos.
Mecanismos aceptados¶
| Mecanismo | Cabecera | Uso |
|---|---|---|
| Sesión como bearer | Authorization: Bearer <session_id> |
Cliente programático que reutiliza una sesión |
| Clave de API | Authorization: Api-Key <api_key> o x-api-key: <api_key> |
Máquina a máquina (recomendado) |
| JWT (OpenID Connect) | Authorization: Bearer <jwt> |
Grupos delegados en un proveedor OpenID Connect |
Cabecera Authorization¶
Los mecanismos basados en la cabecera Authorization —sesión como bearer, clave de API y token OpenID Connect— se utilizan de la misma manera: se coloca el valor exacto de la cabecera en la solicitud. En el ejemplo siguiente, PYSAE_AUTH vale, según el caso, Bearer <session_id>, Api-Key <api_key> o 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 clave de API también acepta la cabecera dedicada x-api-key: <api_key>, equivalente a 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()
Uso máquina a máquina¶
Para una integración automatizada:
- Clave de API (recomendado) — persistente, revocable, acotada por grupo y por rol, sin contraseña en el código que realiza la llamada.
El flujo POST /api/v4/login está pensado para el uso humano (interfaz web) y no se recomienda para la automatización.
El versionado (v2–v5, v4 por defecto) y la división public / internal / datahub se describen en la página de inicio.