canonical: https://jentic.com/apis/is.docs.wso2.com/wso2-identity-claim-management

# Is Docs Wso2 WSO2 Identity Server Claim Management API

Jentic publishes the only available OpenAPI specification for WSO2 Identity Server Claim Management API, keeping it validated and agent-ready. The API administers claim metadata in WSO2 Identity Server, covering local claims, claim dialects, and external claims mapped into those dialects. It exposes 18 endpoints for retrieving, creating, updating, and removing claim definitions, plus dedicated import and export operations for transferring claim dialects between tenants. Multi-tenant routing is built into the base URL so administrators can manage claim configurations on a per-tenant basis.

## For AI agents

Administer WSO2 Identity Server claims and claim dialects programmatically - create local claims, map external claim sources to dialects, and import or export claim configurations between tenants.

## Scope

Does not handle user authentication, password resets, or token issuance - use for claim and claim dialect schema management only.

## Capabilities

- Define new local claims with display names, descriptions, and attribute mappings against the local dialect
- Group external claim definitions under custom claim dialects for federated identity flows
- Import a complete claim dialect from a file to bootstrap a new WSO2 tenant configuration
- Export an existing claim dialect for backup or migration to a separate Identity Server deployment
- Update individual external claim mappings inside a dialect without touching the rest of the schema
- Retrieve every claim dialect currently registered on the server for audit or discovery

## Use cases

### Tenant bootstrap with custom claim schema

Provision a new WSO2 Identity Server tenant with a tailored set of claims and dialects rather than relying on the defaults. Administrators import a curated claim dialect file via POST `/claim-dialects/import`, then add tenant-specific local claims through POST `/claim-dialects/local/claims.` The full bootstrap finishes in minutes instead of hours of manual UI configuration.

Example prompt: Import the file enterprise-claims.json as a new claim dialect, then create a local claim 'employeeID' mapped to the http://wso2.org/claims/employeeId URI

### Federated identity claim mapping

Map claims from an external identity provider - for example SAML or OIDC - into the WSO2 dialect system so downstream applications receive consistent attribute names. The agent registers a new claim dialect for the IdP and pushes external claim mappings via POST `/claim-dialects/{dialect-id}/claims`, linking each external claim to a local claim URI for transparent translation.

Example prompt: Create a new claim dialect for https://login.example.com and add an external claim mapping from urn:example:role to http://wso2.org/claims/role

### Claim configuration migration between environments

Export the claim dialect configuration from a staging tenant and re-import it into production to keep environments in sync. Use GET `/claim-dialects/{dialect-id}/export` to retrieve the dialect definition, then POST `/claim-dialects/import` on the target server to apply it. Avoids drift between environments and supports change-controlled releases of identity configuration.

Example prompt: Export claim dialect with id 'aHR0cDovL3dzbzIub3JnL29pZGM' from staging and import it to the production server

### AI agent identity attribute discovery

An AI agent integrating with WSO2 needs to know which user attributes are available before requesting tokens or building consent screens. Through Jentic the agent calls the GET `/claim-dialects/local/claims` operation, parses the returned attribute URIs, and uses them to construct OIDC scope requests with confidence that each claim exists on the tenant. This removes guesswork from cross-system identity flows.

Example prompt: Retrieve all local claims and select those with the dialect URI http://wso2.org/oidc/claim to construct an OIDC scope list

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | `/claim-dialects/local/claims` | Retrieve all local claims on the tenant |
| POST | `/claim-dialects/local/claims` | Add a new local claim |
| GET | `/claim-dialects` | List every claim dialect |
| POST | `/claim-dialects` | Register a new claim dialect |
| POST | `/claim-dialects/import` | Import a claim dialect from a file |
| GET | `/claim-dialects/{dialect-id}/export` | Export a claim dialect for migration |
| POST | `/claim-dialects/{dialect-id}/claims` | Add an external claim under a dialect |

## Key resources

- **Local Claims** — Tenant-scoped claim definitions in the WSO2 local dialect, including create, update, list, and delete operations
- **Claim Dialects** — Named groupings of claims (e.g. SAML, OIDC, SCIM) with full lifecycle endpoints plus import and export
- **External Claims** — Claim definitions inside non-local dialects with mapping back to local claim URIs

## Why Jentic

- **Setup:** Wiring the WSO2 Identity Server Claim Management API by hand means configuring OAuth2 or basic auth against your tenant-specific host, resolving the serverUrl and tenantDomain path variables, and managing token refresh yourself. Through Jentic you install once, import the WSO2 Claim Management API from the API Directory, store the credentials once, and your agent calls it.
- **Permission scoping:** WSO2 puts the dialect id in the URL path (`/claim-dialects/{dialect-id}/...`), so a rule can pin your agent to one claim dialect: it can list and export that dialect's claims and nothing else. You choose the operations it may call, so creating or importing dialects via POST is not included unless you add it.
- **Credential handling:** Your WSO2 OAuth2 client credentials and any basic auth secrets are stored once, encrypted, by your own Jentic One instance and applied at execution time. They never enter the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'import a WSO2 claim dialect' or 'list local claims', and Jentic returns the matching operation with its input schema, so the agent calls the right endpoint without reading the reference docs.

## Related APIs

- **Auth0 Management API** — Hosted identity platform with rules-based claim transformation instead of dialect files
- **Okta Management API** — Enterprise identity provider with profile attribute management as the equivalent of claim dialects
- **Keycloak Admin API** — Open-source identity broker with protocol mappers that play the role of WSO2 claim dialects

## FAQ

### Why is there no official OpenAPI spec for WSO2 Identity Server Claim Management API?

WSO2 does not publish an OpenAPI specification. Jentic generates and maintains this spec so that AI agents and developers can call WSO2 Identity Server Claim Management API via structured tooling. It is validated against the live API and kept up to date. Get started with Jentic One, the self-hosted execution layer.

### What authentication does the WSO2 Claim Management API use?

The spec declares two security schemes: OAuth2 and HTTP Basic. Production deployments typically issue OAuth2 access tokens through the Identity Server's own token endpoint and pass them as Authorization: Bearer headers. Through Jentic, both credential styles are stored encrypted in the vault and never enter the agent context.

### Can I import an entire claim dialect from a file with this API?

Yes. POST `/claim-dialects/import` accepts a multipart upload of a dialect file and registers every claim it contains in one request. PUT `/claim-dialects/import` performs the same operation in update mode against an existing dialect.

### What are the rate limits for the WSO2 Claim Management API?

The spec does not declare rate limits - they are governed by the deployment's gateway throttling policy. Self-hosted WSO2 administrators set per-tenant request quotas in the Identity Server configuration. Validate the limit for your environment before scripting bulk claim updates.

### How do I discover all local claims on a tenant through Jentic?

Search Jentic with the query 'list all claim dialects' or 'retrieve local claims', load the GET `/claim-dialects/local/claims` operation, and execute it with the tenant base URL. The response is an array of claim objects with claim URI, display name, and attribute mapping.

### Does this API expose user records or just claim definitions?

Only claim definitions and dialects. It is the schema layer of WSO2 Identity Server - actual user records, authentication, and consent flows live in separate WSO2 SCIM and OAuth2 endpoints.

### Can I limit what my agent is allowed to do with the WSO2 Identity Server Claim Management API?

Yes. Jentic One is self-hosted, so your own rules decide which operations and credentials the agent may use. Because WSO2 puts the dialect id in the URL path, such as `/claim-dialects/{dialect-id}/export`, you can pin the agent to a single claim dialect and allow only read and export calls like GET /claim-dialects and GET `/claim-dialects/{dialect-id}/export.` Write operations such as POST /claim-dialects or POST `/claim-dialects/import` stay off limits unless you explicitly add them to the agent's allowed set.