List federated group mappings

GET

/api/v1/federation/group-mappings

const url = 'http://localhost:3000/api/v1/federation/group-mappings?organizationId=550e8400-e29b-41d4-a716-446655440000&provider=ENTRA&enabled=true';
const options = {method: 'GET', headers: {'X-API-Key': '<X-API-Key>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request GET \
  --url 'http://localhost:3000/api/v1/federation/group-mappings?organizationId=550e8400-e29b-41d4-a716-446655440000&provider=ENTRA&enabled=true' \
  --header 'X-API-Key: <X-API-Key>'

Lists federated group mappings across all organizations, optionally filtered by organization, provider, or enabled state. Requires Super Admin privileges.

Authorizations

api-key
bearer

Parameters

Query Parameters

organizationId

string format: uuid

Example

550e8400-e29b-41d4-a716-446655440000

Filter by organization

provider

string

Allowed values: ENTRA LDAP

Example

ENTRA

Filter by identity provider

enabled

boolean

Example

true

Filter by enabled state

Responses

200

Mappings retrieved successfully

application/json

object

items

required

List of federated group mappings

Array<object>

object

required

Unique mapping identifier

string format: uuid

organizationId

required

Organization the mapping grants membership in

string format: uuid

provider

required

Identity provider that supplies the app-role / group

string

Allowed values: ENTRA LDAP

externalId

required

Provider role value or group id carried in the token claim

string

externalKind

required

Kind of external identifier (application role or group)

string

Allowed values: APP_ROLE GROUP

externalLabel

Human-readable label captured at mapping time

string

roleId

required

WFM role granted to users matching this mapping

string format: uuid

enabled

required

Whether the mapping is active (resolved at login time)

boolean

createdById

Id of the user who created the mapping

string format: uuid

createdAt

required

When the mapping was created

string format: date-time

updatedAt

required

When the mapping was last updated

string format: date-time

total

required

Total number of mappings matching the query

number

Example

{
  "items": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440002",
      "organizationId": "550e8400-e29b-41d4-a716-446655440000",
      "provider": "ENTRA",
      "externalId": "fleet-operators",
      "externalKind": "APP_ROLE",
      "externalLabel": "Fleet Operators (Entra group)",
      "roleId": "550e8400-e29b-41d4-a716-446655440001",
      "enabled": true,
      "createdById": "550e8400-e29b-41d4-a716-446655440003",
      "createdAt": "2024-01-15T10:30:00Z",
      "updatedAt": "2024-06-20T14:45:00Z"
    }
  ],
  "total": 3
}

401

Unauthorized

403

Forbidden - Super Admin required