Space Roles and Permissions

This page describes how a Space decides what each signed-in user or visitor can see and do: built-in roles, custom Space Roles, the capabilities a role grants, read filters, and when changes take effect.

Built-in and Custom Roles

Every identity in a Space has exactly one role.

Role	Shown as	Access
Admin	Admin - built-in	Every action on every Schema, Flow, Experience, and OAuth 2.0 credential, plus Space settings. Read filters do not apply.
User	User - built-in	Read, create, update, and remove on every Schema; run and cancel every Flow; read every Experience. Read filters do not apply.
Space Role	The role's name	Only the capabilities listed on the role.

Space members and Space identities are assigned a role in Space Settings → Users. A visitor with no identity in the Space, such as a guest, gets the Default Role of the authentication strategy they arrive through.

An organisation Agent joined to a Space starts with User - built-in. To change it, open Organisations → your organisation → Agents, select the Agent, and pick a role in its Spaces table, or select Remove to take the Agent out of the Space. Only Space admins can do either, so these controls appear only for Spaces where you are an admin.

Where Roles Are Configured

Space Roles are listed under Roles in Space Settings → Auth. Click Create Role, or select a role to open Edit Role. A role has a Name and a list of Capabilities, grouped by section:

Section	Grants access to	Actions
Space	The Space itself	Clone, Oauth Authorize
Roles	Another Space Role's configuration	Config Read
Schemas	Records in a Schema	Read (All, By ID, List), Create, Update, Remove, Config Read, and a read Filter
Flows	Running a Flow	Execute, Execute Version, Cancel Execute, Config Read
Experiences	Opening an Experience	Read, Config Read
OAuth 2.0 Credentials	Authorising an OAuth 2.0 credential	Authorize

A role must have at least one capability.

Schema Actions

Action	Allows
Read: All	Listing Records and reading a Record by ID. Selecting it implies By ID and List.
Read: By ID	Reading a single Record by its ID.
Read: List	Listing and querying Records.
Create	Creating Records.
Update	Changing Records and their links.
Remove	Removing Records.
Config Read	Reading the Schema's field configuration.

Read Filters

A Schema capability with a read action can have one read filter. Set it with the Filter button in the Schema's row, which opens Configure Read Filter for the Schema.

The filter limits which Records of that Schema the role can reach:

Lists, queries, and reads by ID return only Records that match the filter.
Update, Remove, and link changes only work on Records that match the filter. A Record outside the filter behaves as if it does not exist.
Records reached through a relationship, such as linked Records shown in an Experience, are limited by the read filter on their own Schema.

A filter can test the Record's fields, its relationships, or both. Relationship conditions can be nested to follow a chain of links.

Context Values

Context value	Shown as	Value
`spaceIdentityId`	Space Identity	The ID of the identity making the request.

Compare Space Identity with a field that stores the identity's ID to give each identity access to its own Records, or to Records linked to them.

Example

A capability that lets an account user read only their own account's published invoices. The filter follows Invoice → Account → Account User → Person, and matches a field on the Person that stores the identity's ID against the current identity:

{
  "type": "schema",
  "schemaId": "<invoiceSchemaId>",
  "actions": ["read"],
  "filter": {
    "type": "and",
    "filters": [
      {
        "type": "relationship",
        "relationshipId": "<invoiceToAccountRelationshipId>",
        "toFilter": {
          "type": "relationship",
          "relationshipId": "<accountUserToAccountRelationshipId>",
          "fromFilter": {
            "type": "relationship",
            "relationshipId": "<accountUserToPersonRelationshipId>",
            "toFilter": {
              "type": "property",
              "path": ["<spaceIdentityFieldId>"],
              "operator": "eq",
              "value": { "type": "contextValue", "valueId": "spaceIdentityId" }
            }
          }
        }
      },
      {
        "type": "property",
        "path": ["<statusFieldId>"],
        "operator": "eq",
        "value": { "type": "literal", "value": "Published" }
      }
    ]
  }
}

When Changes Take Effect

Changes apply on the identity's next request. Users do not need to sign out and back in. This covers:

Saving a role, including its capabilities and read filters.
Changing the role assigned to a member or identity.
Changing the Records a read filter depends on. For example, removing the link between an Account User and an Account removes that account's Records from the user's results straight away.

Rules and Limits

Each capability applies to one Schema, Flow, Experience, Space Role, or OAuth 2.0 credential. When a role contains more than one capability for the same target, only one of them is applied, and which one is not defined.
A Schema capability has one read filter. It covers every read action on that capability, and the update, remove, and link limits above.
Read filters apply only to Space Roles. Identities with Admin - built-in or User - built-in are never filtered.
ligantic spaces roles update and the matching API call replace the role's name and its whole capability list. Capabilities left out of the request are removed.

Managing Roles with the CLI

Command	Purpose
`ligantic spaces roles list`	List the Space's roles with their capabilities.
`ligantic spaces roles show <spaceRoleId>`	Show one role.
`ligantic spaces roles create --name <name> --capabilities <json>`	Create a role.
`ligantic spaces roles update <spaceRoleId> --name <name> --capabilities <json>`	Replace a role's name and capabilities.
`ligantic spaces roles delete <spaceRoleId>`	Delete a role. `--transfer-space-role-id` moves its identities and pending invites to another role. A role that still has identities or invites is not deleted without it.
`ligantic spaces identities set-role <spaceIdentityId> --space-role-id <spaceRoleId>`	Assign a Space Role to an identity. `--role USER` or `--role ADMIN` assigns a built-in role.