BlockAuth Logo
EN

SDK Quickstart

Each guide takes you from zero to production, step by step. Pick the one that matches your app and follow only that one. To finish the integration, follow it to its last page.

How the pieces connect

Pick your stack and hover over a piece or a step to follow it.

  • Block-Auth SDK
  • Your code
  • Hosted by Block-Auth

Your frontend

  • <BlockAuthProvider>Block-Auth SDK. Config with your public apiKey.
  • <FlowBlockAuth />Block-Auth SDK. Login button, then the profile menu.
  • <LinkBlockAuth />Block-Auth SDK. Links the signed-in user of your app.
  • useBlockAuthUser()Block-Auth SDK. User and roles for your UI, read from the SDK state.

Your backend

  • POST /codeYour code. Redeems the code and sets your httpOnly cookie.
  • GET /me · POST /logoutYour code. Who is signed in, checked on load and every 60 s, and logout.
  • GET · POST /linkYour code. Sends your user id as linkExternalId.
  • WebhookYour code. Receives signout and account.unlinked.

Block-Auth

  • DashboardHosted by Block-Auth. Your app, domain, keys and roles.
  • auth.block-auth.ioHosted by Block-Auth. Hosted login: Block-Auth identity (extension or mobile app), Google, Microsoft, MetaMask, Phantom or WalletConnect.
  • BlockchainHosted by Block-Auth. Every session is signed on-chain.
  • Block-Auth APIHosted by Block-Auth. /api/auth/token, /signout and /link/revoke, called with your apiSecret.
  • IdentityHosted by Block-Auth. Your users see their sessions, devices and linked apps, and can close or unlink them.

Widget in your frontend, session in your backend. Your backend routes live under /auth/blockauth, or your authEndpoint, and can use the Block-Auth package for Node.js, PHP, Python or .NET, or plain HTTP.

  1. 1You copy your public apiKey from the Dashboard.
  2. 2Opens the login in a popup (PKCE).
  3. 3Returns a one-time code.
  4. 4The session is signed on-chain.
  5. 5Sends the code to your backend.
  6. 6Redeems code + apiSecret: gets address and roles.
  7. 7On load and every 60 s (sessionCheckSeconds), asks your backend who is signed in; logout closes it.
  8. 8Shares the signed-in user and roles with the rest of your UI.
  9. 9Optional: opens the same login popup to link your existing user.
  10. 10Checks the link status and sends the new code.
  11. 11The user closes a session or unlinks your app in Identity.
  12. 12Signed webhook when the user signs out or unlinks.

Pick your guide

3/4Last step of your pathComplete your guide and Block-Auth is integrated in your app.

Why your backend redeems the code

Never let your backend trust a user address sent by the browser. The browser decides what it sends, and whether an address is signed into your app is public on-chain data: anyone could send another user's address and get their session.

That is why every guide ends the same way: Block-Auth gives the browser a one-time code, useless without your apiSecret, and your backend redeems it at POST /api/auth/token to get the user's address and roles from Block-Auth itself. Only then does it create its own session.