Contents
Start here
TERSL — the language
TERSL/DB — the system
Portal guide
HTTP API
Reference
Portal guide

Grants

The Grants page is where an administrator edits a namespace's companion document, which says what each key may do in that namespace.

What this page is for#

Each namespace has a companion document, {ns}_meta, written in TERSL. Its # Access section says which keys the namespace admits and what each may do; its # Meta section holds the namespace's name, an optional description and the read-only flag. The Grants page (/grants) shows that document as text, lets you edit it, and saves it whole. The language of # Access is described on Keys, grants and visibility; this page describes the editor.

Who can see it#

Administrators only. A limited user who opens the page gets a 404. Limited users learn where their own keys reach from the Keys and Namespaces pages, which list namespace names and never show a grants document.

What is on the page#

The namespace picker#

Namespace lists the account's active namespaces. Choose one and press Open. Until you do, the page says "Choose a namespace."

The document header#

Above the editor, the page names the Document (for example 74XEEJ5_meta) and its CSN. The companion has its own record, so this CSN counts saves of the grants document and is separate from the namespace's own CSN. Links to Explore, History and Keys open those pages for the same namespace.

If the namespace is read-only, a read-only chip appears with the sentence "Writes to this namespace are refused. To lift it, delete (readOnly) from the # Meta line and save." A namespace that has never had a document shows "No document yet. Saving creates it."; until then it admits nobody.

The editor#

The editor is a text area holding the document. A new namespace's document contains an empty # Access section, which admits nobody. The ## Name line and the # Verification section are not shown: the name is changed on the Namespaces page, and the verification section is maintained by the service. When the area is empty, its placeholder shows the shape of a document:

tersl
# (schema: meta v1)
# Access
## 7Q3M9XBK2ADFHNPR
grant(read)
# Meta
## Description
"What this namespace is for."

Each level-2 header under # Access is a key id, and the grant(…) lines under it say what that key may do and where. A grant directly under the key applies to the whole namespace; one under a ### header such as ### Places applies to that part of the tree.

Below the editor are Save and Cancel, with the caption "Saving replaces the whole document." Two report lines summarise the stored document: # Access followed by the number of keys it names, or "absent — nobody is admitted."; and # Meta with whether a Description is present and its first line.

Actions#

Save#

Press Save. The text you submit replaces the stored document in one step, and the service applies the new grants within a few seconds, as it does a revoked key. On success the page says, for example, "Saved 74XEEJ5_meta at CSN 4. Keys: 7Q3M9XBK2ADFHNPR." or "No keys: this document admits nobody."

Comments in the document are not kept; a saved document comes back without them.

What a save refuses#

The editor refuses a save, and stores nothing, when:

  • the portal's check of the document reports any finding, shown with a code such as GRANTS003;
  • the text contains a # Verification section;
  • the text changes the ## Name (rename the namespace on the Namespaces page instead);
  • a key id in # Access is not one of this account's keys.

A refused save shows "Not saved:" followed by the check's messages, verbatim, with the caption "The document on disk is unchanged." Your text stays in the editor so you can correct it. The refusal does not say whether an unknown key id exists anywhere else.

Lift or set read-only#

A namespace is read-only when its # Meta header carries the readOnly flag, written # Meta(readOnly). While it is set, the service refuses writes to the namespace with a 409 and serves reads as usual; Keys, grants and visibility says which keys receive the 409. Every copy is created read-only. To lift the flag, delete (readOnly) from the # Meta line and press Save; to set it, add it. The change is recorded in the namespace's customer log as a namespace.readonly line naming who made it.

Cancel#

Cancel discards your edits and reloads the stored document.