Roles, teams and group mapping

When someone signs in with SSO, Waxell can put them on a team with a role based on their IdP groups.

Group mapping

On the provider (Settings → Identity → edit):

1. Group claim: the claim or attribute that carries the user's groups. Defaults to groups.
   • Microsoft Entra SAML: http://schemas.microsoft.com/ws/2008/06/identity/claims/groups
   • Okta: the claim name you configured (usually groups)
2. Mappings: rows of IdP group → role → team → surface.
   • IdP group: the group value exactly as the IdP sends it. Entra usually sends the group's Object ID.
   • Role: a role slug, for example viewer, developer or admin. Saving fails if the role doesn't exist in the workspace.
   • Team: a team slug in this workspace.
   • Surface (optional): what the person sees: Full Platform, Connect Only or MCP Gateway. See Surfaces by group.

The first mapping whose group the user has wins. On every sign-in Waxell sets that team membership to the mapped role.

Surfaces by group

Give each mapping a surface to decide what members of that group see. For example:

IdP group	Role	Team	Surface
waxell-engineering	developer	engineering	Full Platform
waxell-everyone	viewer	default	Connect Only

• The surface comes from the first matching mapping that sets one. A mapping that leaves surface empty doesn't block a lower one that sets it.
• A mapping can set only a surface, with no role or team.
• It's re-applied at every sign-in, so your IdP stays the source of truth: move someone from waxell-everyone to waxell-engineering in your IdP and their next sign-in moves them from Connect Only to Full Platform.
• If none of a person's groups sets a surface, their surface is left as it is (the provider's surface for new people, or whatever an admin set).
• People provisioned through SCIM get the provider's surface for new people when they're created, and their group's surface at their first sign-in.

Default role and team

Where someone lands when no mapping matches. Set both a role and a team, or leave both blank for no team membership.

Rules worth knowing

• A mapping takes effect only if its team exists in this workspace. A mapping with no team does nothing.
• An unknown role falls back to viewer, the least-privileged built-in role.
• Group values are split on spaces and commas, so group names with spaces won't match. Use names like waxell-engineering, or IDs.
• Google Workspace sign-in doesn't send groups. For Google, use directory sync.

Built-in roles

Role slug	What it can do
owner	Full access to all resources and settings, including deleting the workspace and managing billing
admin	Full access except deleting the workspace and managing billing
developer	Manage agents, runs and API keys; view billing usage but not change plans
agent-author	Compose and publish agents, push tools, workflows and skills, and apply catalog policies; can't delete, approve or read secrets
viewer	Read-only access to agents, runs, policies, billing usage and audit logs
executive	Read-only access to Insights dashboards
billing-admin	Manage billing and view audit logs; no access to technical resources

Workspaces can also define custom roles.

Roles and teams are managed under Settings → Roles and Settings → Teams.