Rules and Grants

For developers who connect a client to OpenBot or extend its server. The examples need the access stated on this page. Start with the developer manual.

Decisions about requests do not have to be made again and again. OpenBot keeps them in two forms:

Form	Looks like	Who checks it
Grant	`apps.call` on `conn-7/search_orders`, allow, in this Chat	OpenBot, by exact match
Rule	“The Programmer may read any repository of the openbot organization, but asks before a push.”	A judge model

A Grant is fast and exact. A Rule covers a whole kind of request.

Grants

A Grant is a kept decision about one capability of one Bot. The Bot never sees its Grants. It only sees that some calls run and some are denied.

Field	Meaning
`capability`	`action`, `target` (`*` for every target) and optional exact `arguments`.
`effect`	`allow` or `deny`. A deny wins.
`scope`	`once` (used up by one call), `chat` (in one Chat) or `lifetime`.
`grantedBy`	The person, Bot or Rule that decided.
`parent`	The Grant of the decider that this Grant came from.
`chat`	The Chat of a Grant with the scope `chat`.
`status`	`active`, `used` or `revoked`.

OpenBot puts the active Grants of a Bot into one policy, with one rule for each Grant. A deny Grant wins over every allow Grant, in any order. When more than one allow Grant covers a call, the first one gives the answer. A once Grant that gives the answer is then used up. See Permissions.

OpenBot makes Grants when a decider answers a request. You can also make one yourself:

curl -H "Authorization: Bearer $OPENBOT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"capability":{"action":"bots.create","target":"*"},"effect":"allow","scope":"lifetime"}' \
  https://api.example.com/v1/bots/$BOT/grants

GET /v1/bots/:botId/grants lists Grants. Add ?status=active to see only active ones.

DELETE /v1/bots/:botId/grants/:grantId revokes a Grant. OpenBot also revokes every Grant that came from it, so Bots below lose what they got through it.

Rules

A Rule is a sentence in plain language for one Bot. When no Grant decides a request, a judge model reads the active Rules of the Bot.

The judge allows only when a Rule clearly allows this request, and denies only when a Rule clearly forbids it. In every other case, the request goes to the decider.
Each allow or deny must quote the text of a Rule. OpenBot checks the quote. Without a real quote, there is no decision.
A deny wins over an allow.
When the judge fails or is slow, there is no decision.

A Rule that a Bot wrote counts only when that Bot is above this Bot in its owner chain, and may use the capability itself.

curl -H "Authorization: Bearer $OPENBOT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"text":"The Programmer may read any repository of the openbot organization, but must ask before it pushes to main."}' \
  https://api.example.com/v1/bots/$BOT/rules

Field	Meaning
`author`	The person or Bot that wrote the Rule.
`status`	`active`, `proposed` or `retired`. Only active Rules count.
`version`	Goes up with each change.

A Rule from a person is active at once. A Bot can propose a Rule in a review. A proposed Rule counts only after a person makes it active:

curl -X PATCH -H "Authorization: Bearer $OPENBOT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"expected":0,"status":"active"}' \
  https://api.example.com/v1/bots/$BOT/rules/$RULE

You can also keep a Rule when you answer a request: send rule with the answer. See Answer a request.

The judge model

The judge uses the Rules model. It is rulesModel in the organization settings. It has no default. When it is null, the judge gives no answer, so a person or a Bot decides. OpenBot keeps each judge answer for the same Rules and the same capability, so the judge does not run again for the same question.

The Rules model can be a language model or a decision model:

A language model writes the whole answer. It quotes the words of each Rule that it uses, and gives its reason.
A decision model writes no text. It picks allow, deny or no_match, and for each Rule it says how likely it is that the Rule decides the request. OpenBot quotes the whole text of each Rule with a likelihood of 0.5 or more. An allow or a deny without such a Rule is no decision.