User login

Log users in from your backend when there is no SDK for your stack. Block-Auth tells your backend which user logged in, so your app never trusts an address sent by the browser. For the full flow with code, see PHP, Python, .NET, Node.js.

Your backend asks for a login link (/api/auth/authorize) and redirects the user to it.
The user logs in on Block-Auth and comes back to your redirectUri with ?code=…&state=….
Your backend redeems the code (/api/auth/token) and gets the user's address and roles.

Every endpoint on this page takes your apiKey and the SHA-256 hash of your apiSecret in the body. No access token is needed. Responses and errors follow the common format; after 10 requests with wrong credentials in a minute, your IP gets 429 Too many requests.

POST/api/auth/authorize

Returns the URL of the Block-Auth login page for your app. Redirect the user to it: the link must be opened within 5 minutes, and the user then has 15 minutes to log in.

Body

Name
apiKey
Type
string
Description
Your app's API key.
Name
apiSecret
Type
string
Description
SHA-256 hash (hex) of your API secret.
Name
redirectUri
Type
string
Description
Where Block-Auth sends the user back. It must be an https URL on your app's validated domain (for example https://your-app.com/blockauth/callback). Any path of that host is valid.
Name
state
Type
string
Description
A random value (up to 512 characters) that you keep in the user's session. Block-Auth returns it with the code; check that it matches to protect your callback against CSRF.

Request

POST

/api/auth/authorize

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"
}'

Response

{
  "success": true,
  "message": {
    "url": "https://auth.block-auth.io/?t=…",
    "expiresAt": "2026-10-22T12:05:00.000Z"
  }
}

POST/api/auth/token

Redeem the code

Exchanges the code your callback received for the user who logged in. The code is valid for 60 seconds and can be redeemed only once, so redeem it as soon as the callback receives it.

Check the state before calling this endpoint. The address in the response is the user's identity in your app: use it to create your own session.

Body

Name
apiKey
Type
string
Description
Your app's API key.
Name
apiSecret
Type
string
Description
SHA-256 hash (hex) of your API secret.
Name
code
Type
string
Description
The code query parameter of your callback.
Name
redirectUri
Type
string
Description
The same redirectUri you sent to /api/auth/authorize.
Name
codeVerifier
Type
string
Description
Only when the code comes from the widget: the codeVerifier it sends to your backend with the code.
Name
linkExternalId
Type
string
Description
Optional. Your own ID for the signed-in user, to link their account to this Block-Auth identity. Up to 255 characters: letters, digits and . _ : | -.

Response

Name
address
Type
string
Description
The user's address. Same value as did.
Name
signedAt
Type
string
Description
When the user signed into your app, in UTC with the format YYYY-MM-DD HH:mm:ss.
Name
signedExpiredAt
Type
string
Description
When that signature expires, in the same format. Your session should not outlive it.
Name
roles
Type
array
Description
The user's roles in your app, as { slug, name }.
Name
externalId
Type
string
Description
Your own ID for this user if their account is linked, or null.

Request

POST

/api/auth/token

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"
}'

Response

{
  "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
  }
}

POST/api/auth/signout

Sign the user out

Call it when the user logs out of your app. It closes the user's Block-Auth sessions for your app, on every device, so the next login asks for authorization again.

An unknown address answers the same as a known one with no open session: closed: 0.

Body

Name
apiKey
Type
string
Description
Your app's API key.
Name
apiSecret
Type
string
Description
SHA-256 hash (hex) of your API secret.
Name
address
Type
string
Description
The address you got from /api/auth/token.

Request

POST

/api/auth/signout

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"
}'

Response

{
  "success": true,
  "message": {
    "closed": 1
  }
}

POST/api/auth/link/revoke

Unlink an account

Only if you use account linking: removes the link between one of your users and their Block-Auth identity, for example when the user deletes their account in your app. The next time they log in with Block-Auth, they have to link again.

revoked is false when that user had no active link.

Body

Name
apiKey
Type
string
Description
Your app's API key.
Name
apiSecret
Type
string
Description
SHA-256 hash (hex) of your API secret.
Name
externalId
Type
string
Description
Your own ID for the user, the one you used when linking. Up to 255 characters: letters, digits and . _ : | -.

Request

POST

/api/auth/link/revoke

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"
}'

Response

{
  "success": true,
  "message": {
    "revoked": true
  }
}

User login

Get a login link

Body

Request

Response

Redeem the code

Body

Response

Request

Response

Sign the user out

Body

Request

Response

Unlink an account

Body

Request

Response