---
title: "Create Mappings"
description: "This page explains how to create external role mappings using the REST API."
stack: "Enterprise Stack (commercial) — version 0.21.0"
stack_version: "0.21.0"
stack_comparison: https://docs.walt.id/community-vs-enterprise.md
canonical_url: https://docs.walt.id/enterprise-stack/administration/access-and-permissions/external-role-mapping/create-mappings
generated: 2026-07-20
---
# Create Mappings

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

## Prerequisites

Before creating mappings:

1. Your IdP is [configured to include roles](https://docs.walt.id/enterprise-stack/administration/access-and-permissions/external-role-mapping/configure-idp.md) in ID tokens
2. The target Enterprise role exists (see [Create Roles](https://docs.walt.id/enterprise-stack/administration/access-and-permissions/roles/create-roles.md))
3. 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:

**Option: CURL**

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

**Option: Request Body**

```json
{
  "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](https://docs.walt.id/enterprise-stack/administration/access-and-permissions/external-role-mapping/conditional-mappings.md)) |

**Response**

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

## Multiple Mappings

Create mappings for different roles:

```bash
# 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:

```bash
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:

```bash
# 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}'
```

**Info:**

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:

```bash
# 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

1. **Create Enterprise roles first** — Mappings reference role IDs that must exist
2. **Use descriptive external role names** — Makes debugging easier
3. **Start with disabled mappings** — Create with `"enabled": false`, test, then enable
4. **Document your mappings** — Keep a record of external role → Enterprise role mappings
5. **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](https://docs.walt.id/enterprise-stack/administration/access-and-permissions/external-role-mapping/manage-mappings.md) — List, view, and delete mappings
- [Test Mappings](https://docs.walt.id/enterprise-stack/administration/access-and-permissions/external-role-mapping/test-mappings.md) — Verify mappings work correctly
- [Conditional Mappings](https://docs.walt.id/enterprise-stack/administration/access-and-permissions/external-role-mapping/conditional-mappings.md) — Add email domain restrictions