Product: SDP
Version: Self-Hosted 1.3.0+ or SaaS
Author: Hélène Zosym
Need
SDP exposes this through the Platform IAM REST API. The reference page for this API is published in the SaaS section of the documentation, and its URLs are written for SaaS. If you copy them as they are on a Self-Hosted installation, you get 404, Realm does not exist, or no response at all.
This article explains how to build the correct URLs for Self-Hosted, which operations are available for users, roles, groups and clients, and the troubleshooting on frequent issues.
Detailed Solution
1. Availability
| Deployment | Platform IAM API |
|---|---|
| SDP SaaS | Available |
| SDP Self-Hosted 1.1.0 | Not available |
| SDP Self-Hosted 1.2.0 and later | Available |
2. Build the base URL for Self-Hosted
The SaaS reference shows URLs such as:
https://{env}.semarchy.net/auth/realms/customer/platform/modulesOn Self-Hosted, two parts of this URL change.
| Part of the URL | In the SaaS documentation | On Self-Hosted |
|---|---|---|
| Host | {env}.semarchy.net, the SaaS environment host | Your global domain: the host of the IAM (Keycloak) component, the same value as global.domain in values.yaml. For example sdp.example.com. |
| Realm | customer, a placeholder for your tenant name | Your site name: global.site_name (matching global.site_id) in values.yaml. The default is selfhosted. |
Self-Hosted base URL:
https://<global domain>/auth/realms/<site name>/platformExample for a default installation on sdp.example.com:
https://sdp.example.com/auth/realms/selfhosted/platform/clientsTwo points cause most of the errors:
- Use the IAM host, not the application host. SDP uses two DNS names: the global domain (
sdp.example.com) for IAM, and<site name>.<global domain>(selfhosted.sdp.example.com) for the applications. The Platform IAM API is served from the global domain. - The realm is not always
selfhosted. It is the site name. If you changedglobal.site_id/global.site_name, use that value. A quick way to find it: it is the first label of the URL you use to open SDP (https://<site name>.<global domain>).
3. Authentication
Call the API with a bearer token obtained for an API client (service account) of the SDP realm that has the required Platform administration roles. The token is requested from Keycloak on the same host and realm:
POST https://<global domain>/auth/realms/<site name>/protocol/openid-connect/tokenSend the token in each request: Authorization: Bearer <access_token>.
4. Operations by object
All paths below are relative to https://<global domain>/auth/realms/<site name>/platform.
| Object | Typical operations | Path |
|---|---|---|
| Users | List, create, update | /users, /users/{user-id} |
| User role mappings | List assigned, list available, add | /users/{user-id}/role-mappings/realm, /users/{user-id}/role-mappings/realm/available |
| User groups | Add a user to a group | /users/{user-id}/groups/{group-id} (PUT) |
| Roles | List | /roles |
| Groups | List, create | /groups |
| Clients | List, create | /clients |
The request and response schemas are the ones in the SaaS reference (replace only the host and realm as described in section 2). Open the matching page on docs.semarchy.com/saas/reference/api/platform/ for the exact body, for example get-clients, get-roles, create-user, update-user.
5. Troubleshooting
| Symptom | Likely cause | Action |
|---|---|---|
404 Not Found on /platform/... | URL copied from the SaaS reference: realm customer, or application host instead of IAM host | Use https://<global domain>/auth/realms/<site name>/platform/... |
Realm does not exist | Wrong realm name | Use the site name (global.site_name), not customer and not the default if you changed it |
404 on every call on 1.1.0 | API not available | Upgrade to 1.2.0 or later |
201 on Create user but "No access assigned" | roles in the body is not applied | Option A or B in section 5 |
GET .../role-mappings/realm returns [] for a new user | This endpoint lists assigned roles only | Call .../role-mappings/realm/available |
401 / 403 | Token missing, expired, or client without the Platform administration roles | Request a new token; check the client's roles |
500 and nothing in Log Explorer | The error is not always indexed in Log Explorer | Read the logs of the dm-core-active pod: kubectl logs <dm-core-active pod> -n <namespace>. If you need help, send these logs to Support together with the exact request. |