API REST

La API de Block-Auth es para tu backend. Úsala para iniciar la sesión de los usuarios sin un SDK de backend, o para leer los usuarios, roles y actividad de tu app.

Si tu stack tiene SDK, no necesitas esta sección para el login: sigue la Guía rápida de los SDKs. Usa la API directamente si trabajas en otro lenguaje o necesitas datos que los SDKs no exponen.

Antes de empezar

Necesitas una app activa en el Dashboard y sus dos claves. Si aún no las tienes, sigue la Guía rápida de integración.

Llama a la API solo desde tu backend. El apiSecret y su hash dan acceso total a tu app: no los envíes nunca al navegador, a una app móvil ni a un repositorio público.

Calcula el hash de tu API secret

La API nunca recibe tu apiSecret en claro. Envía su hash SHA-256 en hexadecimal en minúsculas. Calcúlalo en tu backend a partir de una variable de entorno:

printf '%s' "$BLOCKAUTH_API_SECRET" | sha256sum | cut -d' ' -f1

En el resto de esta sección, apiSecret significa siempre este hash.

Dos tipos de endpoints

• Login de usuarios (/api/auth/*): envías apiKey y apiSecret en el cuerpo de cada petición. Consulta Login de usuarios.
• Datos (/api/app, /api/user, /api/users, /api/roles, /api/logs): envías un token de acceso en la cabecera Authorization. Consulta Datos.

Cada endpoint tiene un ejemplo cURL. Para probarlos en Postman o Insomnia, importa el ejemplo con Import → Raw text.

Obtener un token de acceso

curl -X POST https://wss.block-auth.io/api/signin \
  -H 'Content-Type: application/json' \
  -d '{
    "apiKey": "your_api_key",
    "apiSecret": "sha256_of_your_api_secret"
  }'

{
  "success": true,
  "message": {
    "accessToken": "eyJhbGciOi…",
    "refreshToken": "eyJhbGciOi…"
  }
}

Refrescar el token de acceso

curl -X POST https://wss.block-auth.io/api/refresh \
  -H 'Content-Type: application/json' \
  -d '{ "refreshToken": "your_refresh_token" }'

{
  "success": true,
  "message": {
    "accessToken": "eyJhbGciOi…",
    "refreshToken": "eyJhbGciOi…"
  }
}

Respuestas y errores

Todas las respuestas tienen la misma forma. Si va bien, message contiene los datos; si falla, contiene el motivo en texto.

{ "success": false, "message": "App not active, contact your admin" }

Paginación

Los endpoints de listas aceptan page (desde 1) y limit (de 1 a 100, por defecto 100) y responden:

{
  "success": true,
  "message": {
    "pages": 1,
    "items": [],
    "total": 0
  }
}

• items: los resultados de la página pedida.
• total: cuántos resultados coinciden, sumando todas las páginas.
• pages: la página que has recibido, no el número de páginas. Calcula el número de páginas como ceil(total / limit).