TILLAUTH · OPERATE

Groups.

Teams, departments and on-call rotas, kept in step with your directory or made by hand. Your apps read them from the groups claim, and internal-app rules can let a whole group in, so access follows the directory instead of a list of emails.

01Model

Where groups come from

Source	How it works
Your directory	Entra ID, Okta, OneLogin or any SCIM 2.0 client pushes groups and their members. They stay in step with the directory and are read-only in TillAuth. See Provisioning.
Made here	Name a group in the dashboard or CLI and add people by email. Good for a few admins or a contractor team that isn’t in a directory.

Groups belong to one identity app, and their members are that app's users. Names are unique per app, ignoring case. A deactivated user stays in their groups but counts for nothing until they're active again.

02Manage

In the dashboard and CLI

Open the identity app and choose Groups. Each group shows its members, where it came from and which internal-app rules name it. A user's page lists their groups.

bash

tilldev auth groups my-app
tilldev auth groups my-app create "On call" --member ana@example.com --member bo@example.com
tilldev auth groups my-app add "On call" cy@example.com
tilldev auth groups my-app remove "On call" bo@example.com
tilldev auth groups my-app show "On call"

Owners and admins of the workspace manage groups. Adding people, renaming and deleting ask for approval when your workspace requires it, because a group can let people into internal apps; taking someone out never waits.

03Apps

Groups in tokens

Ask for the groups scope and the id_token and userinfo carry the user's group names, sorted. The signed-in user always lists them.

json

{
  "sub": "8c0e…",
  "email": "ana@example.com",
  "groups": ["On call", "Platform Eng"]
}

A token carries at most 100 groups. When someone is in more, the first 100 are listed and groups_overage is true; ask userinfo or the signed-in user for the full list.

Note

Tokens pick up a group change at their next refresh. Internal apps see it within 15 seconds.

04Internal apps

Let a group in

json

{
  "name": "Ops",
  "paths": ["/ops/*"],
  "action": "allow",
  "require": { "groups": ["On call", "Platform Eng"], "mfa": true }
}

require.groups admits members of any listed group. Emails, domains and groups are alternatives, so any one lets a person in; roles, a second factor and the other requirements still apply on top. Rules use every group a person is in, not just the first 100. The signed assertion your app receives lists the groups too. See Internal apps.

05Reference

API

Operation	Effect
`GET /api/auth/admin/apps/{app}/groups`	Every group, with its source and size.
`POST /api/auth/admin/apps/{app}/groups`	Make a group: `name` and optional `members`.
`GET /api/auth/admin/apps/{app}/groups/{id}`	One group and its members.
`PATCH /api/auth/admin/apps/{app}/groups/{id}`	Rename.
`POST /api/auth/admin/apps/{app}/groups/{id}/members`	`add` and `remove`, by user id or email.
`DELETE /api/auth/admin/apps/{app}/groups/{id}`	Delete.

Changes to a group your directory manages are refused with 409. See the API reference for the full shapes.

06Limits

What to know

Up to 5000 groups per identity app, names up to 200 characters, and up to 1000 member changes per request.
Rules name groups by name. Renaming a group stops rules naming the old name from matching until you update them; the group's page lists the rules that name it.
Every change, from the directory or by hand, is in the audit log.