BlockAuth Logo
EN

Block-Auth

Block-Auth lets people sign in to your app without passwords, with a decentralized identity they control. Your backend gets a verified user from Block-Auth and keeps its own session, its own users and its own rules.

How it works

  1. The user signs in on Block-Auth. Your app opens the Block-Auth login at auth.block-auth.io, in a popup or with a redirect. The user signs in with their Block-Auth identity, from the browser extension or the mobile app, or with Google, Microsoft, MetaMask, Phantom or WalletConnect, and approves the session.
  2. Your backend gets the user. Block-Auth hands back a one-time code. Your backend redeems it with your API secret at POST /api/auth/token and receives the user's address and roles. The browser never decides who the user is.
  3. Your app keeps its session. Your backend creates its own session, as with any other login method, and can link the Block-Auth user to a user you already have.

Every session is signed on Block-Auth's blockchain, and your users can see and close their sessions, devices and linked apps in Block-Auth Identity.

Explore the architecture

Pick your stack to see the pieces you use in your code and how they connect to Block-Auth. 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.

What you get

  • Passwordless login with social accounts, wallets and the Block-Auth extension, on a login page Block-Auth hosts and maintains.
  • Account linking between a Block-Auth identity and the users you already have, without sharing your database.
  • Roles you define in the Dashboard, returned with every login.
  • Signed webhooks when a user signs out (signout) or unlinks your app (account.unlinked).
  • SDKs for React, Vue and Angular, for PHP, Python and .NET, and a WordPress plugin.