Ir al contenido

Autenticación OAuth

Desde el dashboard (Integraciones) creás una app asociada a tu organización. Recibís:

Campo Uso
client_id Identificador público de la app
client_secret Secreto (se muestra una sola vez; si se pierde, rotá)
scopes Permisos otorgados a esa app

El client_secret no va en el browser ni en apps móviles de usuario final: solo en tu backend.

Al crear la app podés elegir qué scopes otorgar (por ejemplo solo dispositivos y carpetas, o también telemetría).

POST /public/v1/oauth/token
Content-Type: application/json
{
"grant_type": "client_credentials",
"client_id": "app_a1b2c3d4e5f678901234",
"client_secret": "secret_…"
}
{
"access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…",
"token_type": "Bearer",
"expires_in": 900,
"scope": [
"devices.read",
"folders.read",
"boards.read",
"telemetry.read"
]
}
Campo Tipo Descripción
access_token string JWT de corta vida
token_type string Siempre Bearer
expires_in number Segundos hasta expiración (por defecto 900 ≈ 15 min)
scope string[] Scopes efectivos de la app
GET /public/v1/devices
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…
Accept: application/json

Cuando expire, pedí un token nuevo (no hay refresh token en v1).

Scope Habilita
devices.read GET /public/v1/devices
folders.read GET /public/v1/folders
boards.read GET /public/v1/boards, GET /public/v1/boards/{boardId}
telemetry.read GET …/telemetry/latest y …/telemetry/history

Si llamás un endpoint sin el scope correspondiente, la API responde 403.

  • El token se firma con un secret distinto al JWT de usuarios del dashboard.
  • Claim aud=public-api: un token de integración no sirve en rutas del dashboard, y viceversa.
  • Rate limit por minuto (editables en Configuración global del dashboard; defaults 120 / 10):
    • Lecturas /public/v1/*: por client_id (public_api_rate_limit_per_minute)
    • Token: por client_id + IP (public_api_token_rate_limit_per_minute)
Código Situación típica
400 / 401 grant_type incorrecto, credenciales inválidas o app revocada
429 Demasiados intentos de token desde la misma IP
503 Emisión de tokens no configurada en el entorno