Authbound sits between your app and your users’ digital identity wallets. Your app asks for proof, such as “this person is over 18”, and the user’s wallet provides it. Authbound checks the proof and tells your app whether it holds up. Authbound receives the wallet’s raw presentation and handles the wallet protocols. Your app receives the verification outcome and the verified claims permitted by your policy.

A verification from start to finish

  1. Your server starts a verification. It sends your secret key and a policy ID to Authbound. Authbound returns a client token and a wallet handoff: a QR code payload or a link.
  2. The browser shows the handoff. Your server passes along the client token and the handoff, but never the secret key.
  3. The user approves in their wallet. The wallet sends its proof straight to Authbound, not to your app.
  4. Authbound checks the proof against the policy: is the credential genuine, from a trusted issuer, unexpired, and does it contain what the policy asked for?
  5. Everyone finds out. The browser sees the new status and can update the page. Authbound sends your server a webhook. Your server can also fetch a signed result at any time.
The SDKs do all of this for you. The Next.js quickstart takes about five files.

Browser for experience, server for trust

This is the one rule to remember. The browser learns the outcome quickly, so use it to move the user along: show a success message, go to the next page. But the browser is controlled by the user, so it can’t be the thing that grants access. Before you unlock an account, change a limit or mark someone as verified in your database, confirm the result on your server. It can come from a webhook or a signed result. Both come from Authbound directly, so the user can’t fake them.

The pieces

Policies

A policy says what the wallet has to prove and which credentials count. For example, pol_age_over_18_eudi_v1 asks for the EU Proof of Age credential’s age_over_18 value first. A wallet without that credential can answer with its PID: age_over_18 if the PID has it, otherwise the date of birth. Start with a built-in preset, or create your own in the dashboard or with the API. Every verification uses exactly one policy.

Verifications

A verification is one attempt to get a wallet to satisfy a policy. The default verification lifetime is 15 minutes. It ends in one of four states:
StatusMeaning
verifiedThe wallet proved everything the policy asked for.
failedThe proof didn’t hold up, or the user declined. A failure_code says why.
canceledYour app canceled it.
expiredThe user didn’t finish in time.
See Identity verification for the in-between states and every failure code.

Keys

Each project has two kinds of key:
  • Secret key (sk_test_..., sk_live_...): your server uses it to create verifications and read results. Never send it to a browser.
  • Publishable key (pk_test_..., pk_live_...): safe to put in browser code. It identifies your project, but can’t create or read anything on its own.

Client tokens

When your server creates a verification, Authbound returns a client token for it. The browser uses the token, together with your publishable key, to follow that one verification’s progress. A client token only works for its own verification, and it expires with it. Someone who copied it could follow that one verification’s progress, but couldn’t touch anything else in your project.

Webhooks

When a verification finishes, Authbound sends an HTTP request to your server with the outcome. Each webhook is signed, so your server can check that it came from Authbound. If your server doesn’t respond successfully, Authbound retries with increasing delays. Your handler may see the same event more than once, so make it safe to run twice. See Webhooks and results.

Signed results

A signed result is Authbound’s record of how a verification ended: the status, the policy, and the values the wallet proved. It’s a JSON Web Token signed by Authbound, so you can store it as evidence and verify it later. Your server fetches it with authbound.verifications.getResult(id).

Issuing credentials

Authbound can also work the other way round: your server puts a credential into the user’s wallet, such as a membership card or employee badge. The shape is the same. Your server creates an offer, the browser shows it as a QR code or link, and the wallet collects the credential from Authbound. See Credential issuance.