PHP, Python, .NET, Node.js

Follow this guide if your pages are rendered on the server, in PHP, Python, .NET or Node.js. At the end your users sign in with Block-Auth and your backend has a verified session for them.

What you'll build

Everything happens in your backend. You don't install anything from Block-Auth in the browser: your pages only need a normal link to sign in and a form to sign out.

Your backend sends the user to the Block-Auth login and receives them back on a callback with a one-time code. It redeems the code with your API secret, gets the user from Block-Auth and creates its own session.

1Your pages → Your backendGET /blockauth/login
2Your backend → Block-AuthPOST /api/auth/authorize
3Your backend → Your pagesRedirect to the login
4Your pages → Block-AuthThe user signs in
5Block-Auth → Your pagesBack with ?code&state
6Your pages → Your backendGET /blockauth/callback
7Your backend → Block-AuthPOST /api/auth/token
8Block-Auth → Your backend{ address, roles }
9Your backend → Your pagesSession cookie and redirect

Your pages

A plain link

Your backend

Block-Auth SDK

Block-Auth

Hosted by Block-Auth

1GET /blockauth/login
2POST /api/auth/authorize
3Redirect to the login
4The user signs in
5Back with ?code&state
6GET /blockauth/callback
7POST /api/auth/token
8{ address, roles }
9Session cookie and redirect

If your frontend is a React, Vue or Angular app, follow the React, Vue or Angular guide instead: it adds the sign-in button with the widget.

Prepare your app

In the Dashboard, create your application and validate its domain, following the Integration Quickstart. The domain is the host your users see (for example your-app.com). For development, use a separate app with a domain like dev.your-app.com (one app per environment).
Copy the apiKey and apiSecret from Applications » Show keys.
Put them in your server's environment:

.env (backend)

APP_URL=https://your-app.com
BLOCKAUTH_API_KEY=your_api_key
BLOCKAUTH_API_SECRET=your_api_secret
SESSION_SECRET=a_long_random_string

Install the client

Install the Block-Auth client for your language. It gives you AuthCodeClient, the same in every language.

npm install @block-auth.io/node express express-session

Your own implementation (no SDK)

The backend packages are optional: they only save you code. Any server, in any language, can do the same with plain HTTP. Send the SHA-256 hash (hex) of your apiSecret, never the secret itself.

Your login route asks for a link and your callback redeems the code:

curl -X POST https://wss.block-auth.io/api/auth/authorize \
  -H 'Content-Type: application/json' \
  -d '{
    "apiKey": "your_api_key",
    "apiSecret": "sha256_hex_of_your_api_secret",
    "redirectUri": "https://your-app.com/blockauth/callback",
    "state": "random_value_kept_in_the_session"
  }'

Every response is { "success": true, "message": … }; for /api/auth/token, message holds address, did and roles. To verify a webhook, compute v1= + HMAC-SHA256 of timestamp.body (the X-BlockAuth-Timestamp header, a dot and the raw body), keyed with the SHA-256 hash of your apiSecret, and compare it with X-BlockAuth-Signature. All the parameters and errors are in User login.