The access API¶

This page is for whoever builds their own application on OS and wants to know what the signed-in person may do, so the application shows only buttons and menus that work. It shows how to make a request to OS, how to read per kind of thing what someone may do, and what allowed_actions on every thing means. What roles and rules are is in Roles and access.

A request to OS¶

• Address. Every route about an organisation is under /api/v1/organisations/{id}, with the organisation's id (org_...).
• Sign-in. Every request carries the signed-in person's access token: Authorization: Bearer <token>. OS decides for that person, in that organisation.
• Lists come in pages: limit (at most 200, 50 by default) and cursor. An answer has items and, when there is more, next_cursor. A list shows only what the person may see, so a page can hold fewer rows than limit while next_cursor still continues.
• Versions. A thing you replace whole (a group, a custom role, an attribute, the rules document) carries version and the ETag header. A change names that version in If-Match; if the thing changed in the meantime, OS answers 409.
• Errors are application/problem+json:

{"type": "about:blank", "title": "Forbidden", "status": 403,
 "detail": "You may grant only what you hold yourself; you do not hold the role org-admin.",
 "request_id": "..."}

A 422 also has errors, a list with field, message and type for each field.

What someone may do, per kind¶

curl -s "$OS/api/v1/organisations/$ORG/access" -H "Authorization: Bearer $TOKEN"

{"organisation_id": "org_...",
 "kinds": [
   {"kind": "organisation", "actions": ["see"]},
   {"kind": "membership", "actions": ["see", "write"]},
   {"kind": "group", "actions": ["see", "write"]},
   ...
 ],
 "core_kinds": [
   {"kind": "model", "actions": ["see", "use"]},
   {"kind": "thread", "actions": ["see", "write", "delete"]},
   ...
 ]}

kinds names every kind of OS and core_kinds every kind of the AI features, always all of them and in the order of AccessKind and CoreAccessKind (below). Each kind carries the actions the person may take on at least one thing of it. Use this to show a menu or a "new" button before you have read a single thing.

The answer never says "no" where something is allowed. It can say "yes" while every thing the person meets is still refused, for example when a rule applies only to things with a label nothing carries. Decide per thing with allowed_actions.

For the AI features this is what the person's rules allow. A request there can still be refused for another reason; show that refusal.

What someone may do, per thing¶

Every thing OS returns carries allowed_actions: the actions the person may take on exactly that thing. Show a button only when its action is in the list; the request behind the button then succeeds.

An organisation has a second list, parent_allowed_actions: what the person may do about it in the organisation above. write there is suspending, resuming and replacing its labels; delete is deleting it. For the top organisation, and for whoever does not reach the one above, that list is empty.

An organisation's service has the same two lists: in parent_allowed_actions, write means the person may give and remove plans and exceptions there and set a demo's end date.

Per kind and per thing, everything applies inside the organisation's service: what it does not hold is in neither list.

The names in the schema¶

The kinds and actions are enums in OS's OpenAPI schema, under stable names, so you can generate your own types from them: