Login de usuarios
Inicia la sesión de los usuarios desde tu backend cuando no hay SDK para tu stack. Block-Auth le dice a tu backend qué usuario ha iniciado sesión, así tu app nunca se fía de una dirección enviada por el navegador. Para el flujo completo con código, consulta PHP, Python, .NET, Node.js.
- Tu backend pide un enlace de login (
/api/auth/authorize) y redirige al usuario a él. - El usuario inicia sesión en Block-Auth y vuelve a tu
redirectUricon?code=…&state=…. - Tu backend canjea el código (
/api/auth/token) y obtiene la dirección y los roles del usuario.
Todos los endpoints de esta página reciben tu apiKey y el hash SHA-256 de tu apiSecret en el cuerpo. No necesitan token de acceso. Las respuestas y errores siguen el formato común; tras 10 peticiones con credenciales incorrectas en un minuto, tu IP recibe 429 Too many requests.
Obtener un enlace de login
Devuelve la URL de la página de login de Block-Auth para tu app. Redirige al usuario a ella: el enlace debe abrirse en menos de 5 minutos, y después el usuario tiene 15 minutos para iniciar sesión.
Cuerpo
- Name
apiKey- Type
- string
- Description
La API key de tu app.
- Name
apiSecret- Type
- string
- Description
Hash SHA-256 (hex) de tu API secret.
- Name
redirectUri- Type
- string
- Description
A dónde devuelve Block-Auth al usuario. Debe ser una URL
httpsen el dominio validado de tu app (por ejemplohttps://your-app.com/blockauth/callback). Vale cualquier ruta de ese host.
- Name
state- Type
- string
- Description
Un valor aleatorio (hasta 512 caracteres) que guardas en la sesión del usuario. Block-Auth lo devuelve junto con el código; comprueba que coincide para proteger tu callback frente a CSRF.
Petición
curl -X POST \
https://wss.block-auth.io/api/auth/authorize \
-H 'Content-Type: application/json' \
-d '{
"apiKey": "your_api_key",
"apiSecret": "sha256_of_api_secret",
"redirectUri": "https://example.com/callback",
"state": "random_value_in_session"
}'
Respuesta
{
"success": true,
"message": {
"url": "https://auth.block-auth.io/?t=…",
"expiresAt": "2026-10-22T12:05:00.000Z"
}
}
Canjear el código
Canjea el code que ha recibido tu callback por el usuario que ha iniciado sesión. El código es válido durante 60 segundos y solo se puede canjear una vez, así que canjéalo en cuanto lo reciba el callback.
Comprueba el state antes de llamar a este endpoint. La address de la respuesta es la identidad del usuario en tu app: úsala para crear tu propia sesión.
Cuerpo
- Name
apiKey- Type
- string
- Description
La API key de tu app.
- Name
apiSecret- Type
- string
- Description
Hash SHA-256 (hex) de tu API secret.
- Name
code- Type
- string
- Description
El parámetro
codede la query de tu callback.
- Name
redirectUri- Type
- string
- Description
La misma
redirectUrique enviaste a/api/auth/authorize.
- Name
codeVerifier- Type
- string
- Description
Solo cuando el código viene del widget: el
codeVerifierque envía a tu backend junto con el código.
- Name
linkExternalId- Type
- string
- Description
Opcional. Tu propio ID del usuario con sesión, para vincular su cuenta con esta identidad de Block-Auth. Hasta 255 caracteres: letras, dígitos y
. _ : | -.
Respuesta
- Name
address- Type
- string
- Description
La dirección del usuario. Mismo valor que
did.
- Name
signedAt- Type
- string
- Description
Cuándo inició sesión el usuario en tu app, en UTC con el formato
YYYY-MM-DD HH:mm:ss.
- Name
signedExpiredAt- Type
- string
- Description
Cuándo caduca esa firma, en el mismo formato. Tu sesión no debería durar más.
- Name
roles- Type
- array
- Description
Los roles del usuario en tu app, como
{ slug, name }.
- Name
externalId- Type
- string
- Description
Tu propio ID de este usuario si su cuenta está vinculada, o
null.
Petición
curl -X POST \
https://wss.block-auth.io/api/auth/token \
-H 'Content-Type: application/json' \
-d '{
"apiKey": "your_api_key",
"apiSecret": "sha256_of_api_secret",
"code": "code_from_your_callback",
"redirectUri": "https://example.com/callback"
}'
Respuesta
{
"success": true,
"message": {
"address": "0x7F85…46D8",
"did": "0x7F85…46D8",
"signedNonce": 3,
"signedAt": "2026-10-22 11:58:41",
"signedExpiredAt": "2026-10-22 12:58:41",
"roles": [
{ "slug": "acme-x7k2p9", "name": "Admin" }
],
"externalId": null
}
}
Cerrar la sesión del usuario
Llámalo cuando el usuario cierre sesión en tu app. Cierra las sesiones de Block-Auth del usuario para tu app en todos sus dispositivos, de modo que el próximo login vuelva a pedir autorización.
Una dirección desconocida responde igual que una conocida sin sesiones abiertas: closed: 0.
Cuerpo
- Name
apiKey- Type
- string
- Description
La API key de tu app.
- Name
apiSecret- Type
- string
- Description
Hash SHA-256 (hex) de tu API secret.
- Name
address- Type
- string
- Description
La
addressque obtuviste de/api/auth/token.
Petición
curl -X POST \
https://wss.block-auth.io/api/auth/signout \
-H 'Content-Type: application/json' \
-d '{
"apiKey": "your_api_key",
"apiSecret": "sha256_of_api_secret",
"address": "0x7F85…46D8"
}'
Respuesta
{
"success": true,
"message": {
"closed": 1
}
}
Desvincular una cuenta
Solo si usas la vinculación de cuentas: elimina el vínculo entre uno de tus usuarios y su identidad de Block-Auth, por ejemplo cuando el usuario borra su cuenta en tu app. La próxima vez que inicie sesión con Block-Auth tendrá que vincularla de nuevo.
revoked es false cuando ese usuario no tenía ningún vínculo activo.
Cuerpo
- Name
apiKey- Type
- string
- Description
La API key de tu app.
- Name
apiSecret- Type
- string
- Description
Hash SHA-256 (hex) de tu API secret.
- Name
externalId- Type
- string
- Description
Tu propio ID del usuario, el que usaste al vincular. Hasta 255 caracteres: letras, dígitos y
. _ : | -.
Petición
curl -X POST \
https://wss.block-auth.io/api/auth/link/revoke \
-H 'Content-Type: application/json' \
-d '{
"apiKey": "your_api_key",
"apiSecret": "sha256_of_api_secret",
"externalId": "user-1234"
}'
Respuesta
{
"success": true,
"message": {
"revoked": true
}
}