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 }'

• Development
• Production

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

Authorizations

• api-key
• bearer

Parameters

Header Parameters

x-organization-id

string format: uuid

UUID of the organization (tenant) the request acts in. It selects the tenant and grants nothing: the server checks membership or an open tenant switch. Not needed for global operations. A malformed value returns 400. API keys are fixed to their own organization; another organization returns 403. The x-organization-source header grants nothing.

Request Body^required

Media typeapplication/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

Logiccloud orchestrate 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

201

Mapping created successfully

Media typeapplication/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

Logiccloud orchestrate 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

Invalid input data or role does not exist

401

Unauthorized

403

Forbidden - Super Admin required

404

Organization not found

409

Mapping already exists for this provider/externalId