Permissions and allowances
What an app can do after it connects: the permission prompt, spending allowances, the wallet's permissions dashboard, revoking, and the capabilities that stay off by default.
After an app connects, everything it does runs on a grant the wallet holds for that one app. We recommend small grants, asked for when a feature first needs them, listed in one dashboard and undone with one tap.
Charging, signing, reading a basket and seeing a field of a Pass each need a grant. The user agreed to each one, can see it and can take it back. This page covers how grants are asked for, how big they are and how they are undone. For the connect moment, and for deciding what your product needs, see Connecting a wallet.
What the standards define
Four standards define the mechanics. Each does a different job.
- The Wallet Application Interface (BRC-100) puts the requesting app's domain on every call, so the wallet can decide what that app is allowed to do and show the user who is asking.
- Wallet permissions and counterparty trust (BRC-116) is the full specification of the permission lifecycle: how a grant is requested, checked, stored, renewed and revoked. The wallet checks permission when the app calls a method, not when it connects.
- Group permissions (BRC-73) lets an app list the permissions it expects to need in its
manifest.json, each with a sentence explaining it. The wallet can then show them together in one prompt. - Prompt liveness (BRC-219) says a request waiting for the user's decision stays open until the user answers. Apps should not time it out, and the wallet must keep the prompt where the user can find it.
The permissions standard defines four kinds of grant, plus one kind of trust:
| Grant | What the user is agreeing to | How long the standard suggests it lasts |
|---|---|---|
| Protocol | This app may sign or encrypt for one named purpose | Until revoked |
| Spending | This app may spend up to an amount a month without asking | Until revoked; spending is counted per calendar month |
| Basket | This app may use one named collection of the user's outputs | Until revoked |
| Pass fields | These fields of this Pass, sent to this named verifier | Until revoked |
| Counterparty trust | This person, through this app, for these purposes | Until revoked; trust in one app does not carry to another |
The standard also sets three behaviours a designer needs to know:
- A refused grant fails the app's call with a permission-denied error. Apps should treat that as an expected answer, not a fault.
- A revoked grant stops working at once. The user is asked again the next time the app needs it.
- The wallet must treat the app's own description text as untrusted, and show amounts from the request's numbers.
Beside the standards sits an independent risk assessment of the interface (BRC-151). It is an opinion, not a specification. Most of the rules on this page come from it.
Where the standard and the risk assessment differ
They disagree in two places, and you have to pick.
Expiry. The permissions standard suggests grants that do not expire: the user can revoke at any time, and expiry produces renewal prompts. The risk assessment says permissions should expire by default, and lasting access should be an unusual choice. This guide follows the risk assessment for spending and anything sensitive. It accepts lasting grants for ordinary signing within one app, provided the dashboard below exists.
Grouping. The permissions standard encourages apps to declare their permissions so the wallet can ask once. The risk assessment warns that a grouped request must not become a way to collect broad consent at onboarding. Both can hold: the wallet shows the group when the app first does something protected, and the user approves some items and declines others.
Asking for a group of permissions
- OK: at the first protected action, listing only what that feature uses, with each item able to be declined on its own.
- Grey area: a group that also covers features the user has not reached yet, each item explained.
- Not OK: everything at onboarding, preselected, with spending and Pass fields bundled in.
Design the permission prompt
A permission prompt describes the consequence in plain words, not the internal term.
| Instead of | Write |
|---|---|
| Allow Level 2 access to protocol ID X. | Allow Example Shop to sign you in until tomorrow. |
| Reveal certificate fields. | Send Example Bar proof that you are over 18. Your name and date of birth won't be shared. |
| Grant spending authorization. | Let The Satoshi Vision charge you up to 5,000 sats (about £2.50) a month for articles. You can stop this at any time. |
A payment approval should show:
- the amount in local currency, with satoshis beside it
- who is asking, by verified app name and domain
- what the payment is for
- whether it is one-off or recurring, and what is left of any allowance
- that the payment is final once accepted
- whether an AI agent started it
Don't
Preselect broad permissions, describe a permission as less than it is, or show a refused prompt again until the user gives in. All three teach people to tap Allow without reading.
Do
Show the app's name from its manifest beside its verified domain in every prompt, and the domain alone when the app has no manifest.
Do
Write the description for each permission your app declares as what the user gets from it: "To save your reading position", not "Protocol access".
Do
Let the user approve some items in a grouped prompt and decline others, and let the app carry on with what was approved.
Don't
Show an amount taken from the app's description text. Show the amount from the request itself, and warn if the two disagree.
While the prompt is open
A permission request can sit unanswered for a while. Somebody reads the details, switches app or comes back after lunch. The prompt liveness standard treats that as normal: the request waits until the user grants or denies it.
Do
Show a waiting state in the app that tells the user their wallet is asking them something, and keep it until the wallet answers.
Don't
Cancel a wallet request because the user has not answered yet. A timeout turns a user who was reading into an error.
On mobile, the standard requires the wallet to keep the prompt available across app switches and screen locks, or to end the request clearly if it cannot.
Spending allowances
Apps that charge often, such as pay-per-article sites, games or APIs, work best with an allowance the user approves once. A good allowance is:
- Small. Only what near-term use needs.
- Short-lived. It expires by default. Lasting access is an unusual, explicit choice.
- Capped over time. Per payment, and also per hour, day and month. A monthly cap alone lets an app spend the whole month at once.
- Revocable. One tap, at any time, without affecting other apps.
Do
Set an allowance to expire by default, and make a lasting allowance an explicit choice the user picks.
Do
Cap an allowance per payment, per hour and per day as well as per month, where the wallet supports it, and show every cap in the same prompt.
Do
Ask the user again when an amount is unusually high, the recipient is new, the payment pattern changes, an allowance that has ended would start again, or the app asks for a new protocol, basket, Pass field, the identity key or key linkage.
The permissions standard tracks one limit per app per calendar month, and that limit starting again each month within a live grant is normal. The shorter caps, per payment, per hour and per day, are a wallet's own policy, which the risk assessment recommends. If your wallet offers them, they belong in the same allowance prompt, not in settings.
Do
Show the date a monthly allowance starts again beside what is left of it: "1,200 of 5,000 sats left, resets 1 December".
See Charging per use for showing spending inside an allowance.
Software that spends on its own is different. We recommend giving it its own wallet with a fixed budget, as Letting an agent spend describes. An allowance on the person's main wallet is the fallback. Its risk is that a bug or an injected instruction can spend the whole allowance, from the wallet that holds everything else, before anybody looks.
An installed desktop or phone app names itself rather than being named by a browser, so a wallet should treat its first allowance request with more care than a website's. Web apps and native apps has the rules.
When the user says no
A refusal is an answer, and the standard says apps treat it as one.
Do
After a refusal, say in one sentence what the app cannot do without the permission, and keep everything else working.
Do
Ask again only when the user next uses the feature that needs the permission, not on the next screen.
The permissions dashboard
A wallet gives users one place to see and undo what each app can do. For each connected app, show:
- the app name and verified domain
- what it can do: payments, signing, specific baskets, identity key, Pass fields, key linkage
- spending limits and what has been used
- when each permission expires
- when the app last used it
- a revoke button
Revoking one app must never affect the user's ability to access or move their funds.
Do
Make a revoke take effect at once, and say what stops working: "The Satoshi Vision can no longer charge you. It will ask again when you next open an article."
The BSV Association publishes reference React components for these prompts and lists, @bsv/brc100-ui-react-components. They map one to one onto the grant types above: the prompt handlers are GroupPermissionHandler, ProtocolPermissionHandler, SpendingAuthorizationHandler, BasketAccessHandler and CertificateAccessHandler, and the review lists are ProtocolPermissionList, SpendingAuthorizationList, BasketAccessList, CertificateAccessList and AccessAtAGlance. They are a starting point, not a substitute for the wording on this page.
https://github.com/bsv-blockchain/brc100-ui-react-components
Keep sensitive capabilities off by default
Key-linkage revelation proves to a third party how keys are connected. It is for audits, and never part of ordinary payments, sign-in, token ownership or social features. If an app needs it, prefer revealing one specific key over a whole counterparty relationship, and explain why in the prompt.
Do
Ask for key linkage fresh each time, name who receives it and what they learn, and keep a local record of what was revealed to whom.
Don't
Let an AI agent approve key linkage, share a Pass, or widen its own permissions.
Open questions
- With a good dashboard, do lasting grants leave people with more forgotten permissions than grants that expire and ask to be renewed? Nobody has tested it on BSV products.
- Do people read a monthly allowance as a limit, or as money already set aside for the app?
- How should a wallet show trust in a person through an app so it is not mistaken for trust in the app itself?
- When a monthly allowance runs out, should the wallet offer a one-time payment, a higher limit, or only a wait? The standard does not say.
Related
- Pay-per-use reader: an allowance from first grant to revoking it
- Connecting a wallet: the connect moment and asking for the minimum
- Signing in: app-specific keys and asking for a Pass
- Charging per use: spending inside an allowance
- Letting an agent spend: an agent's own wallet and budget, the recommended set-up for software
- Errors and failed payments: refused, revoked and used-up permissions
- Wallet setups: operating, reserve and agent wallets
Written from: BRC-100, BRC-116, BRC-73, BRC-219, BRC-151 §4 and §9, @bsv/brc100-ui-react-components, Connecting a wallet.
Checklist
The rules on this page, in a form you can work through.
16 rules