Skip to main content
A grant carries a list of scope entries. Each entry is operation:scope, where the operation prefix is optional. An entry with no prefix means read. Read and write never cross. Read entries are matched literally, so write:x never satisfies a read of x, and a write requires an entry that carries the write operation, so a plain entry never satisfies a write. A Personal Server that does not recognise an operation prefix treats the entry as a scope name it does not hold, matches nothing, and denies.

​
Matching rules

  • The operation is matched exactly. Comparison is case sensitive and the token is lowercase ASCII.
  • Wildcards apply to the scope part only, using the existing scope matcher. write:chatgpt.* is a wildcard over chatgpt scopes; there is no wildcard over operations.
  • An entry whose operation is not recognised authorizes nothing.
  • An entry is a single operation over a single scope. To grant read and write over the same scope, the grant carries two entries.

​
Operations

Computing a result over a user’s data is not a scope prefix. The question travels in the access request or is registered on the Personal Server, and the resulting grant is an ordinary read on the scope the answer lands in. See Derivative data.

​
Scope names

The prefix is the only part of the string this grammar defines. The scope name itself is declared by the schema and stays dot separated, source first, lowercase.

​
What builders see

You should not construct or parse these strings by hand. The string form is a wire and storage detail: it is what the user signs and what the DP RPC stores. The Vana SDK exposes a grant as scope and actions instead, and consent screens render a table of scope against what the app may do.
  • Every grant the SDK reads back from the DP RPC (getGrant, listGrantsByUser) carries a derived permissions field: one { scope, actions } row per scope pattern, with actions drawn from "read" and "write". The signed scopes array is left untouched.
  • grantPermissions(scopes) produces that grouped view from any scope list, and permissionsToScopes(permissions) is its inverse, so you can build a grant request from checkboxes without writing a prefix.
  • hasAction(scopes, scope, action) answers “does this grant let me write notes.entries?” using the same matcher the Personal Server uses.
  • parseScopeEntry(entry) and formatScopeEntry({ scope, action }) handle a single entry when you need one.
An entry the SDK does not recognise is never treated as read: parseScopeEntry and grantPermissions throw, hasAction skips it, and permissions is left absent on the grant so a consent screen cannot show such a grant as narrower than it is.