API methods - attribute groupings

An attribute grouping gives a name to a set of values held against a user attribute, so that policies can be written against the group name rather than against every individual value.

When the /userinfo endpoint returns a user’s attributes, the Auth Server expands each attribute value with the names of any active groupings that value belongs to. For example, given an active grouping with the attribute permitted_nationalities and a group name of NATO with members ["GBR", "USA", ...], a user holding:

{
  "permitted_nationalities": ["GBR"]
}

is returned:

{
  "permitted_nationalities": ["GBR", "NATO"]
}

A grouping never removes a value a user already has — matched group names are added to the existing values.

Attributes and members

The grouping mechanism is deliberately generic: a grouping may be declared against any attribute. Members are only constrained for those attributes where the platform defines the permitted values:

Attribute	Member constraints
`permitted_nationalities`	Members must be ISO 3166-1 alpha-3 country codes. Members are stored upper cased and matched case-insensitively.
Any other attribute	No constraints. Members are stored as given (whitespace trimmed) and matched exactly.

In all cases, members are trimmed, blank entries are dropped, and duplicates are removed before the grouping is stored. A grouping must have an attribute, a group name, and at least one valid member.

The attribute named in a grouping is the attribute key as returned by /userinfo (for example permitted_nationalities), not the internal attribute name held against the user.

Groupings can also be created at startup from seed data. Seeding only ever creates groupings — an existing grouping is left unchanged, and one deleted through this API is never recreated — so groupings are safe to manage here after the first startup.

Permissions

The attribute grouping endpoints reuse the existing attribute permissions rather than introducing new ones, so they are available to the ADMIN_USER role:

API method	Endpoint	Required permission
`Get attribute groupings`	GET /attribute-groupings	`attributes.read`
`Get attribute grouping by ID`	GET /attribute-groupings/{attributeGroupingId}	`attributes.read`
`Create an attribute grouping`	POST /attribute-groupings	`attributes.write`
`Update an attribute grouping`	PUT /attribute-groupings/{attributeGroupingId}	`attributes.write`
`Delete an attribute grouping`	DELETE /attribute-groupings/{attributeGroupingId}	`attributes.write`

A request made without the required permission returns 403 Forbidden with no response body.

Get attribute groupings

To access this endpoint you must have attributes.read permission.

GET /attribute-groupings

Both active and inactive groupings are returned. Deleted groupings are never returned.

Query parameters:

Parameter	Required	Description
`attribute`	No	Return only the groupings declared against this attribute. If omitted or blank, all groupings are returned.

For example, GET /attribute-groupings?attribute=permitted_nationalities.

Responses:

Status: 200 - attribute groupings returned

Response body example:

{
  "count": 1,
  "attributeGroupings": [
    {
      "id": "3f1c2a77-9b4e-4f2a-8c65-2a1d0e7b4f10",
      "attribute": "permitted_nationalities",
      "groupName": "NATO",
      "members": ["GBR", "USA", "FRA", "DEU"],
      "active": true,
      "createdAt": "2025-11-19T12:09:26.401003",
      "updatedAt": "2025-11-19T12:09:26.401008"
    }
  ]
}

count is the number of groupings returned.

Get attribute grouping by ID

To access this endpoint you must have attributes.read permission.

GET /attribute-groupings/{attributeGroupingId}

Responses:

Status: 200 - attribute grouping returned

Response body example:

{
  "id": "3f1c2a77-9b4e-4f2a-8c65-2a1d0e7b4f10",
  "attribute": "permitted_nationalities",
  "groupName": "NATO",
  "members": ["GBR", "USA", "FRA", "DEU"],
  "active": true,
  "createdAt": "2025-11-19T12:09:26.401003",
  "updatedAt": "2025-11-19T12:09:26.401008"
}

Status: 404 - attribute grouping not found

Create an attribute grouping

To access this endpoint you must have attributes.write permission.

POST /attribute-groupings

Request body example:

{
  "attribute": "permitted_nationalities",
  "groupName": "NATO",
  "members": ["GBR", "USA", "FRA", "DEU"]
}

Field	Required	Description
`attribute`	Yes	The attribute the grouping applies to, as returned by `/userinfo`.
`groupName`	Yes	The name of the grouping, for example `NATO`. May also be supplied as `group-name`.
`members`	Yes	The attribute values that are members of the grouping. At least one valid member is required.

A new grouping is created as active. The combination of attribute and groupName must be unique.

Responses:

Status: 200 - attribute grouping created and returned

Response body example:

{
  "id": "3f1c2a77-9b4e-4f2a-8c65-2a1d0e7b4f10",
  "attribute": "permitted_nationalities",
  "groupName": "NATO",
  "members": ["GBR", "USA", "FRA", "DEU"],
  "active": true,
  "createdAt": "2025-11-19T12:09:26.401003",
  "updatedAt": "2025-11-19T12:09:26.401008"
}

Status: 400 - attribute grouping already exists

{
  "error": "conflict",
  "error_description": "An attribute grouping with this attribute and group name already exists."
}

Status: 400 - invalid request

Returned when the attribute or group name is missing, when there are no valid members, or when a member is not valid for the attribute (for example a permitted_nationalities member that is not an ISO 3166-1 alpha-3 code).

{
  "error": "invalid_request",
  "error_description": "Invalid create attribute grouping request"
}

Update an attribute grouping

To access this endpoint you must have attributes.write permission.

PUT /attribute-groupings/{attributeGroupingId}

Request body example:

{
  "members": ["GBR", "USA", "FRA", "DEU", "ITA"],
  "active": false
}

Only the values to be updated need to be sent in the request. The attribute and the group name cannot be changed — to rename a grouping, delete it and create a new one.

Field	Description
`members`	Replaces the current members in full. If supplied, it must contain at least one valid member.
`active`	Set to `false` to stop the grouping being applied to `/userinfo` attributes without deleting it, or `true` to apply it again.

Responses:

Status: 200 - attribute grouping updated and returned

Response body example:

{
  "id": "3f1c2a77-9b4e-4f2a-8c65-2a1d0e7b4f10",
  "attribute": "permitted_nationalities",
  "groupName": "NATO",
  "members": ["GBR", "USA", "FRA", "DEU", "ITA"],
  "active": false,
  "createdAt": "2025-11-19T12:09:26.401003",
  "updatedAt": "2025-11-21T09:14:02.118221"
}

Status: 400 - invalid request

Returned when members is supplied but empty, or when a member is not valid for the grouping’s attribute.

{
  "error": "invalid_request",
  "error_description": "Attribute grouping members cannot be empty"
}

Status: 404 - attribute grouping not found

Delete an attribute grouping

To access this endpoint you must have attributes.write permission.

DELETE /attribute-groupings/{attributeGroupingId}

Deletion is a soft delete. The grouping is marked deleted and inactive and is retained so that seed data cannot recreate a grouping an administrator has removed. Deleted groupings are not returned by the API and are never applied to /userinfo attributes.

Creating a grouping again with the same attribute and group name revives the deleted grouping with the members given in the create request, rather than failing as a duplicate.

Responses:

Status: 204 - attribute grouping deleted

Status: 404 - attribute grouping not found