Signing in
Signing somebody in with their wallet when there are no accounts or passwords: the first visit, returning visits, signing out, and asking for one fact from a Pass.
Signing in means the app asks the user's wallet for a key and recognises that key next time. We recommend a key derived for your app alone, one Connect wallet button for first and returning visits, and no Pass unless a feature needs one.
There is no account to create, no password to set and nothing to reset. The user sees one button and one approval in their wallet. Identity explains the concepts underneath: identity keys, app-specific keys, Passes and mutual authentication. This page is about designing with them.
What sign-in is when there are no accounts
The wallet derives a public key for your app from its own keys (key derivation, BRC-42), scoped by a protocol name (BRC-43). Your app stores that key as the account. To prove later that a request comes from the same person, the wallet signs it. Apps and services can authenticate each other this way (mutual authentication, BRC-103), including over ordinary web requests (BRC-104).
Three things follow for the design:
- First visit and return visit are the same action. There is nothing to register.
- There is no password to forget. The account is lost only if the wallet is. A wallet restored from its recovery words derives the same key, so the account comes back with it.
- A different wallet is a different person as far as your app can tell.
Do
Use one button for a first visit and a return visit. There is no separate sign-up, because there is no account to create.
Don't
Ask for an email address or a password as part of signing in. If you need an email for receipts, ask for it afterwards, as its own optional step.
Sign-in with an app-specific key
For ordinary sign-in, use a key derived for your app, not the wallet's root identity key.
Do
Sign users in with a key derived for your app. If your database leaks, the leaked keys can't be matched to the same person's activity elsewhere.
Don't
Use the root identity key as the account ID for a social network, game, shop or payment service. One breach then becomes a cross-app tracking event.
Don't
Request the wallet's root identity key without a reason you can state in the prompt. Approving a sign-in or a payment must never include it.
A wallet asks for specific approval before sharing the root identity key.
Returning visits
When the user comes back, the wallet already holds the permission it granted your app, so it gives the same key without asking again. The permissions standard suggests such grants last until the user revokes them (BRC-116). Your app keeps its own session the usual way.
Do
Recognise a returning user without a wallet prompt where the wallet already holds your app's permission.
Don't
Show a public key as the user's name. Use the name they gave you, or a plain label such as "Your account".
Do
Tell people before their first sign-in that the account belongs to their wallet: "Restore this wallet and your account comes back with it. A different wallet is a new account."
Signing out and switching identity
Two different things end a relationship with an app, and people confuse them.
Signing out ends the app's session. The app forgets who is using it on this device. The wallet still lists the app and its permissions.
Revoking happens in the wallet. It removes the app's permissions, and the app has to ask again next time (see Permissions and allowances).
Switching identity means signing out and continuing with a different wallet. Each wallet gives your app a different key, so the app sees a different account. That is the point.
Do
Say on sign-out that the app is still connected in the wallet, and where to disconnect it: "Signed out. Pixel Arcade is still listed in your wallet. Remove it there to stop it asking."
Don't
Call sign-out "Disconnect wallet". It does not touch the wallet's permissions, and the user will think it did.
Asking for a Pass
No Pass by default. Payments, posting, gaming and token transfers work pseudonymously unless a feature needs identity.
When a Pass is needed:
- Ask for the minimum field. "Over 18", not date of birth. "Eligible country", not a full address.
- State the purpose. Do not reuse a Pass across unrelated features because it happens to be available.
- Accept more than one issuer. Wherever you can, accept equivalent Passes from several qualified issuers.
- Show your trust rules. Say which issuers you accept and who decides.
- Explain revocation. Tell users what stops working if their Pass is revoked.
- Offer an alternative. Where the law allows, provide another way to qualify.
Do
Ask for the narrowest field that answers the question: "over 18", not a date of birth.
Do
Say which Pass issuers you accept, and offer another way to qualify where the law allows.
An example prompt:
Example Bar wants proof you're over 18.
Issued by: Example ID Service
Shared: "Over 18: yes"
Not shared: your name, date of birth or address
[Share] [Not now]Why this matters
Revoking a Pass does not delete the user's identity key or freeze their funds. But if many apps require the same Pass from the same few issuers, one revocation can lock somebody out of much of what they use. Design so that a missing Pass is the exception, not the default.
The standard supports this. A request for a Pass names the fields wanted and the verifier who will receive them, and the user approves field by field (BRC-116). A grant for "over 18" does not cover a later request for "over 18" and a name: the wallet asks again.
Don't
Make a Pass a condition of signing in when only one feature needs it. Ask at that feature.
What to show the user
After the first sign-in, the user has just approved something in a wallet they may not open often. Close the loop in the app.
Do
After the first sign-in, say in one line what your app received and what it cannot see: "Pixel Arcade can recognise you next time. It can't see your balance or your other apps."
Show the signed-in state where the account matters, by the name the user chose, with sign-out one step away.
Open questions
- Do people understand that a different wallet means a different account, or do they expect the app to find them?
- Somebody who loses their wallet with no backup loses the account. Should apps offer a fallback, and can they without asking for more than a key?
- How should one person link two wallets to one account without revealing key linkage, which this guide keeps for audits?
- Do people distinguish signing out from disconnecting, even with the wording above?
Related
- Connected web app: signing in on a whole site, from first visit to second device
- Identity: identity keys, app-specific keys, Passes and mutual authentication
- Connecting a wallet: the connect moment
- Permissions and allowances: what the app holds afterwards, and revoking it
- Errors and failed payments: a refused or revoked permission
- Wallet privacy: why an app-specific key protects people
Written from: BRC-100, BRC-42, BRC-43, BRC-52, BRC-103, BRC-104, BRC-116 §4.4, BRC-151 §3, Identity.
Checklist
The rules on this page, in a form you can work through.
14 rules