Groups

GET    /orgs/{orgId}/api/v1/admin/groups
POST   /orgs/{orgId}/api/v1/admin/groups
GET    /orgs/{orgId}/api/v1/admin/groups/{groupId}
PUT    /orgs/{orgId}/api/v1/admin/groups/{groupId}
DELETE /orgs/{orgId}/api/v1/admin/groups/{groupId}
GET    /orgs/{orgId}/api/v1/admin/groups/{groupId}/members
POST   /orgs/{orgId}/api/v1/admin/groups/{groupId}/members
DELETE /orgs/{orgId}/api/v1/admin/groups/{groupId}/members/{userId}
GET    /orgs/{orgId}/api/v1/admin/groups/{groupId}/roles
POST   /orgs/{orgId}/api/v1/admin/groups/{groupId}/roles
DELETE /orgs/{orgId}/api/v1/admin/groups/{groupId}/roles/{roleId}

Groups organize users and carry role assignments. Users inherit all roles from their groups at token issuance time.

Authentication

All group management endpoints require a valid admin API key or a Bearer token issued to a user with settings.manage permission.

The Group Object

Group Object

{
  "id": "01JF3KABCDE...",
  "name": "engineering",
  "displayName": "Engineering Team",
  "description": "Software engineers and SREs",
  "memberCount": 24,
  "roles": ["developer", "deploy"],
  "createdAt": "2026-01-15T10:30:00Z",
  "updatedAt": "2026-03-01T08:00:00Z"
}

List Groups

List Groups

curl "https://app.lumoauth.dev/orgs/acme-corp/api/v1/admin/groups?page=1&limit=50" \
  -H "Authorization: ApiKey lmk_abc123"

Query Parameters

Parameter	Description
page	Page number (default: 1)
limit	Results per page (default: 20, max: 100)
search	Filter by name or display name

Create Group

Create a Group

curl -X POST https://app.lumoauth.dev/orgs/acme-corp/api/v1/admin/groups \
  -H "Authorization: ApiKey lmk_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "engineering",
    "displayName": "Engineering Team",
    "description": "Software engineers and SREs"
  }'

Returns 201 Created with the new group object.

Update Group

Update a Group

curl -X PUT https://app.lumoauth.dev/orgs/acme-corp/api/v1/admin/groups/01JF3KABCDE... \
  -H "Authorization: ApiKey lmk_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "displayName": "Engineering & SRE",
    "description": "Software engineers, SREs, and DevOps"
  }'

Members

List Members

List Group Members

curl "https://app.lumoauth.dev/orgs/acme-corp/api/v1/admin/groups/01JF3KABCDE.../members" \
  -H "Authorization: ApiKey lmk_abc123"

Add Members

Accepts a single userId, an array userIds, or a users array.

Add a Single Member

curl -X POST https://app.lumoauth.dev/orgs/acme-corp/api/v1/admin/groups/01JF3KABCDE.../members \
  -H "Authorization: ApiKey lmk_abc123" \
  -H "Content-Type: application/json" \
  -d '{"userId": "01JF3KUSER..."}'

Bulk Add Members

curl -X POST https://app.lumoauth.dev/orgs/acme-corp/api/v1/admin/groups/01JF3KABCDE.../members \
  -H "Authorization: ApiKey lmk_abc123" \
  -H "Content-Type: application/json" \
  -d '{"userIds": ["01JF3KUSER...", "01JF3KUSER2..."]}'

Remove Member

Remove a Member

curl -X DELETE \
  "https://app.lumoauth.dev/orgs/acme-corp/api/v1/admin/groups/01JF3KABCDE.../members/01JF3KUSER..." \
  -H "Authorization: ApiKey lmk_abc123"

Role Assignment

Roles assigned to a group are inherited by all group members.

note

System roles cannot be assigned to groups.

Get Group Roles

Get Group Roles

curl "https://app.lumoauth.dev/orgs/acme-corp/api/v1/admin/groups/01JF3KABCDE.../roles" \
  -H "Authorization: ApiKey lmk_abc123"

Add a Role to a Group

Assign a Role to a Group

curl -X POST https://app.lumoauth.dev/orgs/acme-corp/api/v1/admin/groups/01JF3KABCDE.../roles \
  -H "Authorization: ApiKey lmk_abc123" \
  -H "Content-Type: application/json" \
  -d '{"roleId": "01JF3KROLE..."}'

Remove a Role from a Group

Remove a Role from a Group

curl -X DELETE "https://app.lumoauth.dev/orgs/acme-corp/api/v1/admin/groups/01JF3KABCDE.../roles/01JF3KROLE..." \
  -H "Authorization: ApiKey lmk_abc123"

Delete Group

Delete a Group

curl -X DELETE "https://app.lumoauth.dev/orgs/acme-corp/api/v1/admin/groups/01JF3KABCDE..." \
  -H "Authorization: ApiKey lmk_abc123"

Returns 200 on success. Members are not deleted — only their group membership is removed.