Reference: groups, markets, access

The group object

Creating, renaming and deleting a group needs an administrator as the key's person, as in Settings › Groups. Members are not managed through the API — they come from the CMS, single sign-on or a directory.

GET /groups · GET /groups/{id} · GET /groups/ref/{ref}

Scope read. Every group by name, { "data": Group[] } — or one.

POST /groups · PUT /groups/ref/{ref}

Scope write. Body { "name": "…", "description": "…" }. POST answers 201; PUT by reference creates (201) or updates (200), so the same request twice leaves one group. A name another group has is 409.

PATCH /groups/{id} · PATCH /groups/ref/{ref}

Scope write. Rename, or change the description.

DELETE /groups/{id} · DELETE /groups/ref/{ref}

Scope write. 204. Its memberships go with it, and so does every grant it held.

Markets

A market is a country: its code (DE, AT) keys every titles object and does not change. { "id", "code", "name", "locale", "isDefault" }. Writing needs an administrator as the key's person, as in Settings › Markets.

GET /markets · GET /markets/{code}

Scope read. Every market by code, { "data": Market[] } — or one. GET /markets now also answers each market's id.

POST /markets

Scope write. { "code": "AT" } adds the market for a country — 201, or 200 with the market that is already there.

PATCH /markets/{code}

Scope write. { "name": "Österreich", "isDefault": true } — either or both. Making one market the default ends it for the one before.

DELETE /markets/{code}

Scope write. 204. Removes the market and every title given in it; if it was the default, the next one by code takes over.

Access

Who may read a category or a document is decided by grants: a group or one person, and a level — read, full, or none. A category's grants apply to everything below it until a grant further down says otherwise; none takes away what a category above gives. A document's own grants are exceptions to what its categories give.

The access object

{
  "grants": [
    { "groupId": "3f2c…", "groupRef": "REGION-NORD", "level": "read", "inherited": false },
    { "userEmail": "anna@example.com", "level": "full", "inherited": true }
  ]
}

inherited (categories only) marks a grant set on a category above, not on this one.

GET /categories/{id}/access · GET /categories/ref/{ref}/access

GET /documents/{id}/access · GET /documents/ref/{ref}/access

Scope read, and full rights on the category or document for the key's person.

PUT /categories/{id}/access · PUT /categories/ref/{ref}/access

PUT /documents/{id}/access · PUT /documents/ref/{ref}/access

Scope write, full rights. The body is the whole set of explicit grants — a subject left out has none here and inherits:

{
  "grants": [
    { "groupRef": "REGION-NORD", "level": "read" },
    { "userEmail": "anna@example.com", "level": "full" }
  ]
}

Name each grant's subject exactly once: groupId, groupRef or userEmail (a member of the organisation). An unknown reference or address is 400, naming it in issues.

For a document, "restrictToGrantedUsers": true makes it readable for the people named only: every group its categories would let in gets none. That holds for the groups that reach it when you send it — a group given access to the category later is not held back.