Authentication

La API de Routal usa API keys para autenticar cada petición. Las keys están scopeadas a una única organización y conceden los mismos permisos que el usuario que las creó.

Cómo se usan

Pasa tu key como query parameter private_key en cada petición:

curl -G 'https://api.routal.com/v2/vehicles' \
  --data-urlencode 'private_key=YOUR_KEY'

Para métodos que aceptan body (POST, PUT), mantén private_key en el query string y pon el payload en el body:

curl -X POST 'https://api.routal.com/v2/plan?private_key=YOUR_KEY&project_id=...' \
  -H 'Content-Type: application/json' \
  -d '{"label": "Hello"}'

La API no acepta keys en el header Authorization hoy.

Formato de la key

Las API keys son strings alfanuméricos aleatorios con el prefijo api_key_ (p. ej. api_key_xY7…32 chars). Trata el string completo como el secreto — no hay una "parte secreta" separada que extraer.

Generar y gestionar keys

Crea, etiqueta, desactiva y borra keys desde el dashboard del planner:

planner.routal.com/h/settings/developers/api-keys

Cada key tiene:

• Un label que tú eliges (p. ej. staging-integration, analytics-readonly) — sólo para tu propio control.
• Un flag active — cuando vale false la key se rechaza al autenticar. Útil para revocar temporalmente sin borrar.
• Un timestamp created at.

No hay timestamp last_used_at hoy — desde el dashboard no puedes saber cuándo (ni si) se ha usado una key concreta.

Puedes tener múltiples keys activas a la vez por organización, lo que hace la rotación indolora.

Seguridad

• Trata la key como una contraseña. Cualquiera con la key puede leer y modificar cada plan, route, stop y vehicle de tu organización (a través de los proyectos a los que tenga acceso el usuario creador).
• Nunca subas keys a un repositorio. Usa variables de entorno (process.env.ROUTAL_API_KEY) o un secret manager (1Password, Doppler, AWS Secrets Manager, Vault).
• Nunca metas una key en una URL que termine en logs. La mayoría de logs de servidor y los HTTP intermediaries capturan URLs enteras, query string incluido. Cuando puedas, loguea solo el path y redacta el query string antes de persistirlo. Este es el riesgo práctico más grande de la auth por query string.
• Código del browser es no-go. Una key enviada al browser es una key pública. Si necesitas llamar a la API desde el browser, proxyea por tu propio backend.

Rotación

Rota keys con cadencia regular (cada 90 días es un buen default) e inmediatamente si sospechas exposición.

El patrón recomendado:

1. Genera una key nueva en el dashboard. Mantén la existente activa.
2. Despliega tus servicios con la nueva key.
3. Una vez que estés seguro de que nada sigue usando la vieja (ventana de despliegue + margen), pon el flag active de la vieja a false desde el dashboard. Si algo seguía llamándola verás fallos de auth — puedes reactivarla al instante.
4. Tras otra ventana sin reactivaciones, borra la key vieja definitivamente.

Este swap zero-downtime funciona porque Routal soporta múltiples keys activas simultáneamente por organización.

Permisos y scoping

Las API keys hoy son scoped a la organización: pueden leer y modificar cualquier recurso al que tenga acceso el usuario creador. No hay scoping per-key (read-only vs. read-write, scoping a nivel de proyecto, IP allowlist, etc.).

Si tu integración solo necesita acceso de lectura, aíslala detrás de tu propia capa de servicio.

Scopes granulares están en el roadmap. Si tienes un caso de uso concreto, contáctanos.

Lo que viene

• Quickstart — lanza tu primera llamada autenticada.
• Errors — qué pasa cuando una key falta, está mal formada o desactivada. (Spoiler: cada fallo de auth con API key se reporta hoy como highway.apiKey.error.not_found.)