---
title: "Manage Mappings"
description: "This page covers how to list, view, update, and delete external role mappings."
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/manage-mappings
generated: 2026-07-20
---
# 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):

**Option: CURL**

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

**Option: Response**

```json
[
  {
    "externalRole": "tenant-admin",
    "roleId": "waltid.tenant1.BW_ADMIN",
    "enabled": true,
    "providerId": null,
    "conditions": null
  },
  {
    "externalRole": "wallet-operator",
    "roleId": "waltid.tenant1.BW_OPERATOR",
    "enabled": true,
    "providerId": null,
    "conditions": null
  }
]
```

**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:

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

Response:

```json
[
  {
    "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:

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

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

**Info:**

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:

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

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

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

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

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

```json
[
  {
    "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

**Error:**

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](https://docs.walt.id/enterprise-stack/administration/access-and-permissions/external-role-mapping/test-mappings.md) — Verify mappings before relying on them
- [Conditional Mappings](https://docs.walt.id/enterprise-stack/administration/access-and-permissions/external-role-mapping/conditional-mappings.md) — Add restrictions to mappings