Saltar a contenido

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-keys crea una. El cuerpo acepta group_ids, label, expire y scopes; se rechaza cualquier campo que designe un principal (user_id, role, superuser, device_id). Con group_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. Sin group_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, en value.
  • GET /api/v4/users/me/api-keys lista 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.