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.

const groupId = process.env.GROUP_ID

const url = new URL("https://api.pysae.com/api/v4/auth/provider")
url.searchParams.set("group_id", groupId)

const response = await fetch(url)
if (!response.ok) {
  throw new Error(`Provider lookup failed: ${response.status}`)
}

// { provider: "legacy" } or { provider: "auth0", auth0: { domain: ... } }
console.log(await 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": ...}.

const email = process.env.EMAIL
const password = process.env.PASSWORD

const response = await fetch("https://api.pysae.com/api/v4/login", {
  method: "POST",
  headers: { "Content-Type": "application/x-www-form-urlencoded" },
  body: new URLSearchParams({ email, password }),
})
if (!response.ok) {
  throw new Error(`Login failed: ${response.status}`)
}

const { session_id: sessionId } = await response.json()

Automatización — POST /api/v4/login-scoped. Destinado a la automatización: los parámetros de consulta scopes y expire acotan la sesión (alcance y fecha de caducidad). Mismo cuerpo (email, password) y misma respuesta.

const email = process.env.EMAIL
const password = process.env.PASSWORD

const url = new URL("https://api.pysae.com/api/v4/login-scoped")
url.searchParams.append("scopes", "read")
url.searchParams.set("expire", "2026-12-31")

const response = await fetch(url, {
  method: "POST",
  headers: { "Content-Type": "application/x-www-form-urlencoded" },
  body: new URLSearchParams({ email, password }),
})
if (!response.ok) {
  throw new Error(`Scoped login failed: ${response.status}`)
}

const { session_id: sessionId } = await response.json()

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.

const groupId = process.env.GROUP_ID
const sessionId = process.env.SESSION_ID
const userId = process.env.USER_ID

const response = await fetch(
  `https://api.pysae.com/api/v4/groups/${groupId}/api-keys`,
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${sessionId}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ user_id: userId }),
  },
)
if (!response.ok) {
  throw new Error(`API key creation failed: ${response.status}`)
}

const { value: apiKey } = await response.json()

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.

Para la limpieza automatizada, una clave superuser con scopes: ["delivery-flags.read"] solo autoriza GET /api/v4/delivery-flags entre las rutas protegidas. El rol superuser sigue siendo obligatorio. El alcance rechaza las escrituras, /delivery-flags/changes y la creación de otras claves; no modifica las rutas anónimas.

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

| Cookie de sesión | Cookie: session_id=<session_id> | Navegador — se establece automáticamente tras el inicio de sesión | | WebSocket | Cabecera Authorization/Cookie, o primer mensaje {"session_id": "<session_id>"} | Flujos en tiempo real |

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>.

const groupId = process.env.GROUP_ID
const authorization = process.env.PYSAE_AUTH

const url = new URL(
  `https://api.pysae.com/api/v4/groups/${groupId}/export/trips`,
)
url.searchParams.set("date", "20260131")

const response = await fetch(url, { headers: { Authorization: authorization } })
if (!response.ok) {
  throw new Error(`Request failed: ${response.status}`)
}

La clave de API también acepta la cabecera dedicada x-api-key: <api_key>, equivalente a Authorization: Api-Key <api_key>:

const groupId = process.env.GROUP_ID
const apiKey = process.env.PYSAE_API_KEY

const url = new URL(
  `https://api.pysae.com/api/v4/groups/${groupId}/export/trips`,
)
url.searchParams.set("date", "20260131")

const response = await fetch(url, { headers: { "x-api-key": apiKey } })
if (!response.ok) {
  throw new Error(`Request failed: ${response.status}`)
}

Tras un inicio de sesión correcto, la API devuelve el session_id en una cookie Set-Cookie (httponly, secure, samesite=lax). Un navegador la reenvía automáticamente en cada solicitud; un cliente manual la adjunta explícitamente:

curl --cookie "session_id=<session_id>" \
  "https://api.pysae.com/api/v4/groups/<group_id>/export/trips"

WebSocket

Una conexión WebSocket reutiliza el session_id. Un cliente que puede establecer cabeceras lo envía mediante Authorization: Bearer <session_id> o la Cookie, como en HTTP. Un cliente que no puede hacerlo (WebSocket de navegador) lo envía en el primer mensaje JSON de la conexión:

const groupId = process.env.GROUP_ID
const sessionId = process.env.SESSION_ID

const socket = new WebSocket(
  `wss://api.pysae.com/api/v4/groups/${groupId}/events/op/subscribe`,
)

socket.addEventListener("open", () => {
  socket.send(JSON.stringify({ session_id: sessionId }))
})
socket.addEventListener("message", (event) => {
  console.log(event.data)
})

Una conexión rechazada —session_id ausente o no válido, ningún rol en el grupo— recibe el JSON del error como mensaje y después se cierra con el código 1008 (infracción de política). A diferencia de un cierre normal (1000), una reconexión con las mismas credenciales se volverá a rechazar: corrija la autenticación antes de volver a conectarse. En cambio, un error del servidor cierra la conexión con el código 1011 (error interno): en ese caso puede volver a intentarlo más tarde.

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.

  • login-scoped — sesión acotada por scopes y expire, cuando es preferible una credencial de duración limitada a una clave permanente.

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.