# Update IdP group mappings list.

`PUT /api/configuration/authentication/consumer-sso-idp-groups`

- **Success:** `204 No content`
- **Products:** Operator (`FOH`)
- **Features:** Front of House Generic Access (`FOHGENERIC`)

HTML version: [Update IdP group mappings list.](https://support.gladstonesoftware.cloud/reference/configuration/update-idp-group-mappings-list)

## Overview

Replaces the whole set of consumer single sign-on IdP group mappings in one call. Each mapping ties a
group in your external identity provider to a price level at a site, so members who arrive through
SSO in that IdP group are automatically assigned that price level.

**The request body is the complete desired set, not a list of changes.** What you send is compared
against what is stored, and the difference is applied:

- an entry with `id: null` is **created**;
- an entry with an existing `id` is **updated** — and only if at least one of its four values
  actually differs, compared case-insensitively;
- **any stored mapping whose id is absent from your request is deleted.**

**Sending an empty array therefore deletes every mapping.** Read the current set with
`GET /api/configuration/authentication/consumer-sso-idp-groups` first, apply your change to that
list, and send the whole thing back.

The comparison is by `id` only, so re-sending an existing mapping without its `id` does not match it:
you get a new mapping created and the original deleted, and the duplicate checks below will usually
reject the attempt first.

Validation covers the entire request before anything is written, and the writes are then applied
together and undone on failure — so this call is all-or-nothing. On success the response is
`204 No Content` and the change is visible on the next read.

## Endpoint

`PUT {base_url}/api/configuration/authentication/consumer-sso-idp-groups`

`{base_url}` is the environment URL issued to your integration. See [Authenticating with Gladstone APIs](../../guides/authenticating-with-gladstone-apis.md).

## Request body

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `[].id` | integer (int32) | No | Identifier of an existing mapping, from `GET /api/configuration/authentication/consumer-sso-idp-groups`. Send `null` — or omit the property — to create a new mapping; the id is allocated for you. Any non-null value must match a stored mapping or the whole request fails with `400 Invalid id(s): {ids}`, which includes `0` and negatives. The same id must not appear twice (`400 Duplicate Id(s) found: {ids}`). Omitting a stored id from the request is how you delete that mapping. |
| `[].groupName` | string | Yes | Your label for the mapping, used to identify it in listings. Mandatory, maximum 255 characters (`The mapping name can not be longer than 255 characters`), and leading and trailing whitespace is trimmed on the way in. Must be unique across the whole request, compared case-insensitively — two entries differing only in case fail with `400 Duplicate GroupName(s) found: {names}`. |
| `[].idpGroupID` | string | Yes | The group identifier as your identity provider issues it — the value matched against the signing-in user's groups. Mandatory, maximum 255 characters (`The Idp group id can not be longer than 255 characters`), trimmed on the way in. Must be unique across the request, case-insensitively (`400 Duplicate IdpGroupID(s) found: {ids}`), so one IdP group cannot be mapped twice in a single call — including to two different sites. |
| `[].priceLevelID` | string | Yes | The price level to assign to members arriving through this IdP group. Mandatory, maximum 15 characters (`The price level id can not be longer than 15 characters`), trimmed on the way in, and it must already exist as a price level — the check is case-insensitive and the request fails with `400 The following PriceLevelID(s) do not exist: {ids}` otherwise. |
| `[].siteId` | string | Yes | The site the mapping applies at. Mandatory, maximum 15 characters (`The site id can not be longer than 15 characters`), trimmed on the way in, and it must already exist as a site — checked case-insensitively, failing with `400 The following SiteId(s) do not exist: {ids}`. Unlike `groupName` and `idpGroupID`, the same site may appear on many entries. |

## Sample request

```bash title="cURL"
curl -X PUT '{base_url}/api/configuration/authentication/consumer-sso-idp-groups' \
  -H 'Authorization: Bearer {accessToken}' \
  -H 'X-Use-SSO: true' \
  -H 'Content-Type: application/json' \
  -d '[
  {
    "id": 12345,
    "groupName": "string",
    "idpGroupID": "string",
    "priceLevelID": "string",
    "siteId": "string"
  }
]'
```

## Sample response

```json title="204 No content"
1
```

## Errors

| Status | Meaning | When |
|--------|---------|------|
| `400` | Bad request | Validation failed: any of `groupName`, `idpGroupID`, `priceLevelID` or `siteId` missing, or over its maximum length. The body is a validation error object, keyed by the index and field within the array. |
| `400` | Bad request | An `id` was supplied that does not exist — `Invalid id(s): {ids}`. Checked first, so it masks the duplicate and existence checks below. |
| `400` | Bad request | Two entries share a `groupName`, ignoring case — `Duplicate GroupName(s) found: {names}`. |
| `400` | Bad request | Two entries share an `idpGroupID`, ignoring case — `Duplicate IdpGroupID(s) found: {ids}`. |
| `400` | Bad request | Two entries share an `id` — `Duplicate Id(s) found: {ids}`. |
| `400` | Bad request | A `priceLevelID` does not exist — `The following PriceLevelID(s) do not exist: {ids}`. |
| `400` | Bad request | A `siteId` does not exist — `The following SiteId(s) do not exist: {ids}`. |
| `500` | Internal server error | An unexpected server-side failure. All writes are undone before this is returned, so no mapping is created, changed or deleted. No detail is returned. |