Skip to main content
A group is a named collection of scopes defined at the application level. Assign a user to a group and, on their next login, the group’s scopes are added to their access token. Groups let you manage authorization by role — admins, editors, billing — instead of granting scopes to each user one by one.

​
Prerequisites

  • A Prelude account with access to the Auth API
  • An Application ID (appID) — see Applications
  • Your Management API key for backend calls
  • One or more allowed scopes declared on the application — see Scopes

​
How it works

A group owns a set of scopes, and every scope a group owns must be one of the application’s allowed scopes. Users are assigned to groups; a user can belong to several groups. Two things happen at different times:
  • At session creation (login), the user’s current group membership is snapshotted onto the session.
  • At every access-token mint (login and refresh), each group on the session is looked up in the current application configuration and the scopes of the matching groups are merged into the token’s scope claim — alongside the user’s own scopes.
This split has two consequences worth remembering:
Membership is pinned at session creation. Adding or removing a user from a group does not change the scopes of their already-active sessions — it takes effect the next time they log in. Changing the scopes a group owns, on the other hand, is reflected on the next access-token refresh of every existing session, because group scopes are resolved from the live configuration at mint time.

​
Configure groups

1

Declare the scopes on your application

A group can only own scopes the application already allows. Add them first:
curl -X POST https://api.prelude.dev/v2/session/apps/{appID}/config/scopes \
  -H "Authorization: Bearer $MANAGEMENT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "scope": "read" }'
2

Create a group

Create a group and give it a subset of the allowed scopes. A group name is unique per application and may contain letters, digits, - and _.
curl -X POST https://api.prelude.dev/v2/session/apps/{appID}/config/groups \
  -H "Authorization: Bearer $MANAGEMENT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "admins", "scopes": ["read", "write"] }'
If any scope is not in the application’s allowed scopes, the request fails with scope_not_allowed and lists every offending scope.
3

Assign users to the group

Assign a user to the group. The call is idempotent — assigning a user who is already a member succeeds without changing anything.
curl -X POST https://api.prelude.dev/v2/session/apps/{appID}/users/{userID}/groups \
  -H "Authorization: Bearer $MANAGEMENT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "group": "admins" }'
The next time the user logs in, their access token’s scope claim will include read and write.
4

(Optional) Expose group names as a claim

Group scopes always land in the scope claim. If you also want the group names in the token, map the groups input in your claims mapping:
{ "roles": { "$input": "groups", "$type": "string-array" } }
This adds e.g. "roles": ["admins"] to the token. Group names are resolved from the user’s profile, so this claim stays in sync with membership changes on the next claims recomputation.

​
Update or remove a group

Replace a group’s scopes with PUT /config/groups/{groupName}; the new set takes effect on the next access-token mint of every session that belongs to the group. 
curl -X PUT https://api.prelude.dev/v2/session/apps/{appID}/config/groups/admins \
  -H "Authorization: Bearer $MANAGEMENT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "scopes": ["read", "write", "admin"] }'
Remove a single user from a group with DELETE /users/{userID}/groups/{groupName} (idempotent), or delete the group definition entirely with DELETE /config/groups/{groupName}. Once a group is deleted, its scopes are no longer granted at mint time.
Group membership and group scopes are enforced only through the access token minted by Prelude. Always authorize sensitive operations on your backend against the scope claim of a freshly minted (or refreshed) access token, not against a cached one.

​
API reference