#Manage Mappings

This page covers how to list, view, update, and delete external role mappings.

#List All Mappings

Get all mappings within a scope (organization or tenant):

CURL

Response

curl -X GET \
  'https://{host}/v1/waltid/roles-api/roles/external-mappings' \
  -H 'Authorization: Bearer {token}'

Path Parameters

Parameter	Description	Example
`scope`	Organization or tenant scope	`waltid` or `waltid.tenant1`

#List Mappings for a Specific Role

Get mappings targeting a specific Enterprise role:

curl -X GET \
  'https://{host}/v1/waltid.tenant1.BW_ADMIN/roles-api/roles/external-mappings' \
  -H 'Authorization: Bearer {token}'

Response:

[
  {
    "externalRole": "tenant-admin",
    "roleId": "waltid.tenant1.BW_ADMIN",
    "enabled": true
  },
  {
    "externalRole": "super-admin",
    "roleId": "waltid.tenant1.BW_ADMIN",
    "enabled": true
  }
]

#Update a Mapping

Update an existing mapping by calling PUT with new values:

curl -X PUT \
  'https://{host}/v1/waltid.tenant1.BW_ADMIN/roles-api/roles/external-mappings/tenant-admin' \
  -H 'Authorization: Bearer {token}' \
  -H 'Content-Type: application/json' \
  -d '{
    "enabled": false
  }'

Common updates:

Disable temporarily: {"enabled": false}
Add provider restriction: {"enabled": true, "providerId": "keycloak"}
Add conditions: {"enabled": true, "conditions": {"emailDomains": ["company.com"]}}

#Delete a Mapping

Remove a mapping permanently:

curl -X DELETE \
  'https://{host}/v1/waltid.tenant1.BW_ADMIN/roles-api/roles/external-mappings/tenant-admin' \
  -H 'Authorization: Bearer {token}'

Response

204 No Content — Mapping deleted (or didn't exist)

DELETE is idempotent — calling it on a non-existent mapping succeeds without error.

#Bulk Operations

#Clear All Mappings for a Role

Delete all mappings targeting a specific role:

curl -X DELETE \
  'https://{host}/v1/waltid.tenant1.BW_ADMIN/roles-api/roles/external-mappings' \
  -H 'Authorization: Bearer {token}'

#Replace All Mappings for a Role

Replace all mappings with a new set:

curl -X PUT \
  'https://{host}/v1/waltid.tenant1.BW_ADMIN/roles-api/roles/external-mappings' \
  -H 'Authorization: Bearer {token}' \
  -H 'Content-Type: application/json' \
  -d '[
    {"externalRole": "admin", "enabled": true},
    {"externalRole": "super-admin", "enabled": true}
  ]'

This removes any existing mappings and creates the specified ones.

#Enable/Disable Mappings

Toggle mappings without deleting them:

#Disable a Mapping

curl -X PUT \
  'https://{host}/v1/waltid.tenant1.BW_ADMIN/roles-api/roles/external-mappings/tenant-admin' \
  -H 'Authorization: Bearer {token}' \
  -d '{"enabled": false}'

#Re-enable a Mapping

curl -X PUT \
  'https://{host}/v1/waltid.tenant1.BW_ADMIN/roles-api/roles/external-mappings/tenant-admin' \
  -H 'Authorization: Bearer {token}' \
  -d '{"enabled": true}'

#Audit Mappings

To review all mappings in your organization:

# List all mappings at org level
curl -X GET \
  'https://{host}/v1/{organization}/roles-api/roles/external-mappings' \
  -H 'Authorization: Bearer {token}' | jq

Example output formatted:

[
  {
    "externalRole": "tenant-admin",
    "roleId": "waltid.tenant1.BW_ADMIN",
    "enabled": true
  },
  {
    "externalRole": "tenant-admin",
    "roleId": "waltid.tenant2.BW_ADMIN", 
    "enabled": true
  },
  {
    "externalRole": "viewer",
    "roleId": "waltid.tenant1.BW_VIEWER",
    "enabled": false
  }
]

#Mapping States

State	Description
Active	`enabled: true` — Mapping is evaluated during login
Disabled	`enabled: false` — Mapping exists but is not evaluated
Deleted	Mapping removed — Does not appear in lists

#Effect on Active Sessions

Changes to mappings take effect on the next login. Users with active sessions retain their original permissions until:

Their session expires
They log out and log back in
Their token is refreshed (if using refresh tokens)

#Next Steps

Test Mappings — Verify mappings before relying on them
Conditional Mappings — Add restrictions to mappings

Last updated on May 7, 2026

Create Mappings Test Mappings