Scopes

A scope says one thing an agent may do. Each scope belongs to a family, named by its domain. This page lists the families and what every scope in them grants. Needs a verified Sigil means the scope can only be used for a person who has completed verification. A mandate carrying it does nothing for an unverified account. Parameters are written as described in The mandate language. A parameter marked required must be present for the scope to be signed at all.

​

Sigil: facts about you

Attestations about the verified person behind the agent, and one read of the agent’s own identity. kyc_read parameters:

• doc_type: limit the read to one kind of document, such as passport or id_card.
• reason: why the details are shared. One of a fixed list.
• requestor: the provider that receives them. One of a fixed list.

Sharing your details with a provider needs a kyc_read scope that carries both reason and requestor. The lists grow as providers are added. The three attestations (kyc_status, proof_of_personhood, age_over_18) are the only scopes a mandate may carry when it is addressed to a website by its hostname. See Resources and conditions.

​

Spend: paying for things

Purchases, which run as errands. max on spend:visa_checkout is the most one checkout may charge, in the display unit of currency. See Spending ceilings.

​

Errand: purchase tasks

Starting, reading and managing errands. errand:search parameters:

• time: how long the errand may keep searching, in seconds. 604800 is seven days. Sumvin also applies its own upper limit, and the shorter of the two wins.
• max: an optional purchase ceiling. It is not enforced, because this scope names no currency to measure it in. Put the ceiling that counts on spend:visa_checkout.

Starting an errand spends nothing. Paying needs a spend scope as well.

​

Accounts and transactions: open-banking data

Linking accounts and reading their data through Meld. With from_date or to_date, the agent can ask only for transactions inside that range. A request reaching outside it is refused.

​

Proofs: facts about your money

Proving something about your money to someone else without showing them the figures. proofs:balance parameters:

• min: the amount being proven, in the display unit of currency. It follows the same rules as a spending ceiling: fractions up to the currency’s precision, positive only. See Spending ceilings.
• currency: the ISO 4217 code the amount is stated in, such as USD.
• timing: when the balance is checked. live checks it each time a proof is made, and is the default. snapshot checks the most recent balance on record. frozen checks it once and holds the answer for the life of the mandate.

​

Read mandates

An agent asking you directly for a mandate asks for one of two kinds:

• Spend: the spend scopes above, with exactly one spending ceiling.
• Read: any of accounts:read, transactions:read and proofs:balance. A read mandate spends nothing and carries no ceiling.

A request mixing the two kinds is refused. To grant both, sign two mandates. See Time limits for how long each lasts.

​

Mandates: asking for and checking mandates

mandates:read covers only your own requests. Checking a mandate that belongs to someone else always needs mandates:verify.

​

Onboarding: setting up your account

​

Your account

Reading what your Sumvin account holds. Your linked accounts and transactions are covered by the accounts and transactions family above.

​

Not listed here

The catalogue also holds scopes for products these docs don’t cover, and a few reserved names with nothing behind them yet. A mandate naming a scope that is not in the catalogue at all is refused.

​

Next