Registro de clientes (RFC 7591)

El Dynamic Client Registration (RFC 7591) permite que tu aplicación se registre como cliente OAuth sin intervención manual del equipo de Whatalo. Cada instalación del mismo software puede obtener su propio client_id.

Endpoint

POST https://app.whatalo.com/oauth/register
Content-Type: application/json

No requiere autenticación previa. El endpoint es público.

Este endpoint tiene un límite de 10 solicitudes por IP por hora. Si lo excedes, recibirás HTTP 429 con el header Retry-After. Cachea el client_id recibido — no necesitas registrarte de nuevo en cada sesión.

Cuerpo de la solicitud

{
  "client_name": "Mi Integración SaaS",
  "redirect_uris": ["https://mi-app.com/oauth/callback"],
  "grant_types": ["authorization_code", "refresh_token"],
  "response_types": ["code"],
  "scope": "read:orders read:products write:orders",
  "token_endpoint_auth_method": "client_secret_post",
  "software_id": "mi-integracion-saas",
  "software_version": "2.1.0",
  "logo_uri": "https://mi-app.com/logo.png",
  "client_uri": "https://mi-app.com",
  "policy_uri": "https://mi-app.com/privacidad",
  "tos_uri": "https://mi-app.com/terminos"
}

Campos del cuerpo

Campo	Requerido	Descripción
`client_name`	Sí	Nombre visible en la pantalla de consentimiento
`redirect_uris`	Sí	Lista de URIs de redirección. Deben ser HTTPS (salvo `localhost`)
`grant_types`	No	Por defecto `["authorization_code"]`. Incluye `"refresh_token"` si necesitas refresh
`response_types`	No	Solo `["code"]` está soportado
`scope`	No	Scopes que la app puede solicitar. Ver Scopes
`token_endpoint_auth_method`	No	`"client_secret_post"`, `"client_secret_basic"`, o `"none"` (cliente público)
`software_id`	No	Identificador estable del software, compartido por todas las instancias
`software_version`	No	Versión opaca del software, solo para auditoría
`logo_uri`	No	URL del logo de la app (se muestra en consentimiento)
`client_uri`	No	URL de la página principal de la app
`policy_uri`	No	URL de la política de privacidad
`tos_uri`	No	URL de los términos de servicio

Respuesta exitosa (201 Created)

{
  "client_id": "abc123def456ghi789jkl012",
  "client_secret": "s3cr3t_v4lu3_xyz987wvu654",
  "client_name": "Mi Integración SaaS",
  "redirect_uris": ["https://mi-app.com/oauth/callback"],
  "grant_types": ["authorization_code", "refresh_token"],
  "response_types": ["code"],
  "scope": "read:orders read:products write:orders",
  "token_endpoint_auth_method": "client_secret_post",
  "software_id": "mi-integracion-saas",
  "software_version": "2.1.0",
  "client_id_issued_at": 1746648000,
  "client_secret_expires_at": 0
}

Campos de la respuesta (RFC 7591 §3.2.1)

Campo	Tipo	Descripción
`client_id`	string	Identificador único del cliente. Guárdalo de forma persistente.
`client_secret`	string	Secreto del cliente (solo para clientes confidenciales). Mostrado una sola vez.
`client_id_issued_at`	number	Timestamp UNIX (segundos) de cuándo se emitió el `client_id`.
`client_secret_expires_at`	number	Timestamp UNIX de expiración del secreto. `0` significa que no expira.

El client_secret se muestra únicamente en esta respuesta. Guárdalo de inmediato en un almacén seguro de secretos — no podrás recuperarlo después.

Clientes públicos (sin secreto)

Si tu app no puede mantener un secreto de forma segura (aplicación de escritorio, extensión de navegador, herramienta CLI), regístrala como cliente público:

{
  "client_name": "Mi App de Escritorio",
  "redirect_uris": ["http://127.0.0.1:PORT/callback"],
  "grant_types": ["authorization_code", "refresh_token"],
  "token_endpoint_auth_method": "none"
}

La respuesta no incluirá client_secret. El flujo de autorización con PKCE sigue siendo obligatorio.

El patrón `software_id`

Cada instalación del mismo software obtiene un client_id distinto — eso es por diseño (RFC 7591 §2). El campo software_id sirve para que Whatalo identifique el paquete de software independientemente de la instancia.

Campo	Por instancia	Estable entre instancias
`client_id`	Sí	No
`software_id`	No	Sí — elige uno fijo para tu software

Cuando el equipo de Whatalo verifica un software_id, todas las instancias heredan automáticamente la insignia de verificación en la pantalla de consentimiento.

Siguiente paso

Con tu client_id en mano, inicia el flujo de autorización.

On this page