Skip to content
Fleet Manager

Create federated group mapping

POST
/api/v1/federation/group-mappings
 
curl --request POST \
  --url http://localhost:3000/api/v1/federation/group-mappings \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <X-API-Key>' \
  --data '{ "provider": "ENTRA", "externalId": "fleet-operators", "externalKind": "APP_ROLE", "externalLabel": "Fleet Operators (Entra group)", "organizationId": "550e8400-e29b-41d4-a716-446655440000", "roleId": "550e8400-e29b-41d4-a716-446655440001", "enabled": true }'

Creates a federated group mapping tying a provider app-role / group to a WFM role within an organization. Requires Super Admin privileges.

Authorizations

Section titled “Authorizations ”

Request Body required

Section titled “Request Body required ”
Media type application/json
object
provider
required

Identity provider that supplies the app-role / group

string
Allowed values: ENTRA LDAP
Example 
ENTRA
externalId
required

Provider role value or group id carried in the token claim

string
<= 255 characters
Example 
fleet-operators
externalKind
required

Kind of external identifier (application role or group)

string
Allowed values: APP_ROLE GROUP
Example 
GROUP
externalLabel

Human-readable label captured at mapping time

string
<= 255 characters
Example 
Fleet Operators (Entra group)
organizationId
required

Organization the mapping grants membership in

string format: uuid
Example 
550e8400-e29b-41d4-a716-446655440000
roleId
required

WFM role granted to users matching this mapping

string format: uuid
Example 
550e8400-e29b-41d4-a716-446655440001
enabled

Whether the mapping is active (resolved at login time)

boolean
default: true
Example 
true

Responses

Section titled “ Responses ”

201

Section titled “201 ”

Mapping created successfully

Media type application/json
object
id
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
Example 
{
  "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"
}

400

Section titled “400 ”

Invalid input data or role does not exist

401

Section titled “401 ”

Unauthorized

403

Section titled “403 ”

Forbidden - Super Admin required

404

Section titled “404 ”

Organization not found

409

Section titled “409 ”

Mapping already exists for this provider/externalId