#Create Mappings

This page explains how to create external role mappings using the REST API.

#Prerequisites

Before creating mappings:

Your IdP is configured to include roles in ID tokens
The target Enterprise role exists (see Create Roles)
You have admin permissions on the target scope

#API Endpoint

PUT /v1/{role}/roles-api/roles/external-mappings/{externalRole}

This endpoint creates or updates a mapping using REST semantics (idempotent).

#Basic Mapping

Map an external role to an Enterprise role:

CURL

Request Body

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": true
  }'

Path Parameters

Parameter	Description	Example
`role`	Target Enterprise role ID	`waltid.tenant1.BW_ADMIN`
`externalRole`	External role name from IdP	`tenant-admin`

Body Parameters

Field	Type	Required	Description
`enabled`	boolean	No	Whether mapping is active (default: `true`)
`providerId`	string	No	Restrict to specific OIDC provider
`conditions`	object	No	Additional conditions (see Conditional Mappings)

Response

201 Created  — New mapping created
200 OK       — Existing mapping updated

#Multiple Mappings

Create mappings for different roles:

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

# Map wallet-operator → BW_OPERATOR
curl -X PUT \
  'https://{host}/v1/waltid.tenant1.BW_OPERATOR/roles-api/roles/external-mappings/wallet-operator' \
  -H 'Authorization: Bearer {token}' \
  -d '{"enabled": true}'

# Map viewer → BW_VIEWER
curl -X PUT \
  'https://{host}/v1/waltid.tenant1.BW_VIEWER/roles-api/roles/external-mappings/viewer' \
  -H 'Authorization: Bearer {token}' \
  -d '{"enabled": true}'

#Provider-Specific Mappings

If you have multiple IdPs, restrict mappings to a specific provider:

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

This mapping only applies when users authenticate through the keycloak-prod provider.

#Multi-Tenant Mappings

In multi-tenant deployments, create separate mappings for each tenant:

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

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

Use descriptive external role names that indicate the tenant (e.g., acme-admin, globex-admin) to avoid conflicts.

#One External Role to Multiple Enterprise Roles

A single external role can map to multiple Enterprise roles by creating multiple mappings:

# Map super-admin to both admin and operator roles
curl -X PUT \
  'https://{host}/v1/waltid.tenant1.BW_ADMIN/roles-api/roles/external-mappings/super-admin' \
  -H 'Authorization: Bearer {token}' \
  -d '{"enabled": true}'

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

Users with super-admin will receive permissions from both roles.

#Best Practices

Create Enterprise roles first — Mappings reference role IDs that must exist
Use descriptive external role names — Makes debugging easier
Start with disabled mappings — Create with "enabled": false, test, then enable
Document your mappings — Keep a record of external role → Enterprise role mappings
Use tenant-scoped roles — For multi-tenant setups, scope roles to specific tenants

#Common Patterns

#Pattern 1: Role Hierarchy

Map IdP roles to a permission hierarchy:

External Role	Enterprise Role	Permissions
`admin`	`BW_ADMIN`	Full access
`operator`	`BW_OPERATOR`	Create, read, update
`viewer`	`BW_VIEWER`	Read only

#Pattern 2: Department-Based

Map department groups to appropriate roles:

External Role	Enterprise Role
`engineering`	`DEVELOPER`
`operations`	`OPERATOR`
`support`	`SUPPORT_AGENT`

#Pattern 3: Tenant Isolation

Each tenant has dedicated external roles:

External Role	Enterprise Role
`tenant-a-admin`	`waltid.tenantA.ADMIN`
`tenant-a-user`	`waltid.tenantA.USER`
`tenant-b-admin`	`waltid.tenantB.ADMIN`
`tenant-b-user`	`waltid.tenantB.USER`

#Next Steps

Manage Mappings — List, view, and delete mappings
Test Mappings — Verify mappings work correctly
Conditional Mappings — Add email domain restrictions

Last updated on May 7, 2026

Configure Identity Provider Manage Mappings