When an organization has more than one or two members, role-based access becomes the day-to-day admin task. This guide walks through creating roles, deciding what they grant, assigning them to members, and inviting new users with the right role from the start.

When to use roles

You need explicit roles whenever:

  • The organization has members who are not owners — owners always have implicit full access; members start with nothing.
  • A schema's access mode is Private — members cannot see it without a role that grants read.
  • Different members should have different scopes of write access (sales can edit customers but not products; finance can read invoices but not edit them).

If everyone in the organization should see everything, the simplest move is to give them all owner status. Roles are the answer when access needs to be different per person.

Anatomy of a role

A role has:

  • Name — what shows up in the assignment dropdown.
  • Description — optional, useful for future you.
  • Capabilities — the list of permissions, grouped by resource. See Roles and capabilities for the catalogue.
  • Scope — which schemas (or specific models) the capabilities apply to.

You build the role once and reuse it on every member who plays that part.

Creating a role

From the organization page → Roles tab → + New role:

  1. Give it a clear, action-oriented name. "Sales agent" reads better than "Role 3".
  2. Pick the schemas (or specific models) the role covers.
  3. Tick the capabilities for each:
    • Read metadata — see the schema and its models. Without this, the rest is unreachable.
    • Read instances, Create, Update, Delete — CRUD per model.
    • Manage files — uploads on instances.
    • Use the AI assistant — let this role's holders chat with the agent.
  4. Save.

Assigning a role to a member

From the Members tab, click a member, then Assign role and pick from the list. A member can have multiple roles — capabilities add up; nothing is taken away by a second role.

The change takes effect on the user's next request to the platform; they do not need to sign out and back in.

Inviting a new user with roles pre-attached

You can invite someone who is not yet a platform user. From Members → + Add member → Invite by email:

  1. Type the invitee's email.
  2. Pick the roles they should land with.
  3. (Optional) Add a short message — included in the invitation email.
  4. Send.

The invitee receives an email with a sign-up link tied to the organization. Once they sign in, they are already a member with the roles you set; no further action on your part.

Pending invitations are listed under Members with a pending badge. You can resend, change roles before acceptance, or revoke.

Editing or deleting a role

From the Roles tab, click a role to edit it. Changes apply to every member who currently holds it. If you delete a role, every member who had it loses those capabilities immediately — they keep any other roles they had.

Roles are scoped to the organization that defined them. There is no global role registry: each organization builds its own set.

A short pattern

For a small team, three or four roles usually cover everything:

  • Admin — full read + write on every schema. Useful when the person should have org-level control but you do not want to make them an owner (no member management).
  • Editor (per area) — read + create + update + manage files on a specific schema (e.g. Sales editor on the CRM schema).
  • Read-only — read instances on a set of schemas, nothing else. Good for auditors, consultants, external advisors.
  • Assistant user — adds the Use the AI assistant capability on top of any of the above when the org wants to gate agent access.

You can split further later — start coarse, refine when a specific case demands it.