Create User Group

Create a user group and receive a userGroupId for use in events (metadata.usergroup) and leaderboards. Auth: JWT or API key — see API reference.

ℹ️

JWT: `sub` claim

With JWT authentication, the sub claim is required and must not be empty — otherwise the request is rejected before it reaches this endpoint. For POST /usergroup, sub has no effect on the created group; it is not used as a user ID. Use any stable service identifier (e.g. backend-integration), not an end-user ID.

Endpoint

POST /usergroup

Request Body

{
  "userGroupId": "your-usergroup-id",
  "title": {
    "default": "Region Unterfranken",
    "de": "Region Unterfranken"
  },
  "description": {
    "default": "Users in Unterfranken",
    "de": "Nutzer in Unterfranken"
  }
}

Omit userGroupId to let the API generate one (e.g. ug_a1b2c3d4e5f6).

Field Descriptions

Field	Type	Required	Description
`userGroupId`	string	No	Your identifier (`a-z`, `A-Z`, `0-9`, `_`, `-`, max 128). Not `"default"`.
`title`	object	Yes	Display name; requires `default` and `de`.
`description`	object	No	Optional; same language keys as `title`.

Example Request

curl -X POST "/v1/usergroup" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "userGroupId": "your-usergroup-id",
    "title": {
      "default": "Region Unterfranken",
      "de": "Region Unterfranken"
    }
  }'

Response

{
  "message": "User group created successfully",
  "userGroupId": "your-usergroup-id",
  "createdAt": 1740000000000
}

Status Codes

Code	Description
201	Created
400	Invalid body or `userGroupId`
401	Missing or invalid auth
409	`userGroupId` already exists
500	Server error

Use the group when sending events:

"metadata": { "usergroup": ["your-usergroup-id"] }

👥 User Groups 💪 Challenges