Groups & Permissions

Groups organise profiles and control access across the ShellApps ecosystem.

Concepts

Groups

A group is a collection of profiles with shared access. Think of groups as teams or organisations.

interface Group {
  id: string;
  name: string;
  description?: string;
  ownerId: string;       // Profile ID of the group owner
  members: GroupMember[];
  createdAt: string;
}

Roles

Each member within a group has a role. Roles define what actions a member can perform.

Role	Description
`owner`	Full control — manage members, roles, settings, delete group
`admin`	Manage members and content, but cannot delete the group
`editor`	Create and edit content within the group's scope
`viewer`	Read-only access

Permissions

Permissions are granular capabilities attached to roles. Services across ShellApps check these permissions when authorising actions.

interface Permission {
  resource: string;    // "experience.pages", "toolshed.integrations"
  actions: string[];   // ["read", "write", "delete"]
}

Built-in permission scopes:

Scope	Description
`experience.pages`	Create/edit pages in Experience
`experience.themes`	Manage themes via the Design System
`toolshed.integrations`	Manage Toolshed integrations
`rapidstack.agents`	Manage RapidStack agents
`auth.members`	Manage group membership

Creating a Group

const response = await fetch('https://auth.shellapps.com/api/v1/groups', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${token}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'My Team',
    description: 'Our project workspace',
  }),
});

Adding Members

await fetch(`https://auth.shellapps.com/api/v1/groups/${groupId}/members`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${token}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    profileId: 'profile_xyz',
    role: 'editor',
  }),
});

Checking Permissions

Services check permissions via the JWT claims or by calling the auth API:

// JWT contains group/role info
const { groups } = decodeJwt(token);
const canEdit = groups.some(g =>
  g.permissions.some(p =>
    p.resource === 'experience.pages' && p.actions.includes('write')
  )
);

Profiles — Profiles belong to groups
API Reference — Group endpoints
Toolshed — Integration permissions

Profiles OAuth Integration