# API endpoints reference The **Segregation of Duties (SoD) API** provides endpoints for managing policies, detecting violations, and handling remediation programmatically. Use this API to integrate SoD controls into automated workflows, governance tools, or custom interfaces. Using the SoD API, you can: * **Create and update policies** that define conflicting roles or entitlements * **Validate access changes** before they are applied * **Query violations** at user, role, or system level * **Trigger remediation workflows** or apply mitigating controls * **Audit and report** on SoD compliance status #### How to use this reference This reference covers: * request and response formats * required parameters and authentication * example calls and expected results Familiarize yourself with core SoD concepts such as **policies**, **violations**, and **remediation** before using these endpoints. ### SoD policy Base URL: `/rest/api/sod-policy` | Endpoint | Method | Description | | ----------------------------- | ------ | ----------------------------------------------------------------------------------------------------------------------------- | | `/rest/api/sod-policy/search` | GET | Search policies. Params: `name`, `resourceIds`, `groupIds`, `roleIds`, `organizationIds`, `from`, `size`, `sortBy`, `orderBy` | | `/rest/api/sod-policy/{id}` | GET | Get a single policy by ID | | `/rest/api/sod-policy/save` | POST | Create or update a policy (body: full policy + segments) | | `/rest/api/sod-policy/{id}` | DELETE | Delete a policy | #### Create or update a policy **REST endpoint:** `POST /rest/api/sod-policy/save` A new policy is created with a name, description, severity, and at least one segment. The request body (`SodPolicyBean`) supports: * setting the policy active or inactive * linking mitigating controls by ID * defining one or more segments, each with conflicting role, group, resource, or organization IDs #### Search policies **REST endpoint:** `GET /rest/api/sod-policy/search` Supported filters: | Parameter | Description | | -------------------- | ---------------------------------------- | | `name` | Substring match on policy name | | `resourceIds` | Policies referencing these resources | | `groupIds` | Policies referencing these groups | | `roleIds` | Policies referencing these roles | | `organizationIds` | Policies referencing these organizations | | `from` / `size` | Pagination | | `sortBy` / `orderBy` | Column and direction for sorting | #### Delete a policy **REST endpoint:** `DELETE /rest/api/sod-policy/{id}` Removes the policy and its segments. Existing exemptions and historical violation records are retained for audit purposes. Audit action generated: `DELETE_SOD_POLICY` ### Mitigating controls Base URL: `/rest/api/sod/mitigating-controls` | Endpoint | Method | Description | | ------------------------------------------ | ------ | ------------------------------------------------ | | `/rest/api/sod/mitigating-controls/search` | GET | Search controls. Params: `name`, `from`, `size` | | `/rest/api/sod/mitigating-controls/{id}` | GET | Get a single control by ID | | `/rest/api/sod/mitigating-controls/save` | POST | Create or update a control | | `/rest/api/sod/mitigating-controls/{id}` | DELETE | Delete a control (blocked if linked to policies) | ### Violations Base URL: `/rest/api/sod-policy-violation` | Endpoint | Method | Description | | ------------------------------------------------------- | ------ | --------------------------------------------------------------------------------------- | | `/rest/api/sod-policy-violation/impacted-users/detect` | POST | Trigger on-demand violation detection across all users | | `/rest/api/sod-policy-violation/impacted-users/search` | GET | Search users with violations. Params: `name`, `login`, `sodPolicyBeans`, `from`, `size` | | `/rest/api/sod-policy-violation/{userId}` | GET | Get all violations for a user | | `/rest/api/sod-policy-violation/{userId}/{sodPolicyId}` | GET | Get violated entitlements for a specific user + policy combination | | `/rest/api/sod-policy-violation/handle-violations` | POST | Remove or whitelist entitlements to resolve a violation | #### Trigger detection **REST endpoint:** `POST /rest/api/sod-policy-violation/impacted-users/detect` This triggers a system-wide re-evaluation of all users against all policies. Detection is also triggered automatically when: * A policy is saved or updated. * A user's entitlements change via provisioning. #### Query violations | Endpoint | Description | | ----------------------------------------------------------- | ------------------------------------------------------------ | | `GET /rest/api/sod-policy-violation/impacted-users/search` | List all users with at least one policy violation | | `GET /rest/api/sod-policy-violation/{userId}` | Summary of all violated policies for a specific user | | `GET /rest/api/sod-policy-violation/{userId}/{sodPolicyId}` | Detailed entitlements violating a specific policy for a user | The detailed response includes the specific conflicting entitlements (direct and indirect), the segment that defines the conflict, and whether each violation has been resolved. ### Remediation #### Remove conflicting access **REST endpoint:** `POST /rest/api/sod-policy-violation/handle-violations` (with `isDelete=true`) Removes the specified conflicting entitlements from the user via the provisioning service. This is the standard remediation path. #### Grant an exemption **REST endpoint:** `POST /rest/api/sod-policy-violation/handle-violations` (with `isDelete=false`) Creates a formal exemption that allows the user to retain the conflicting entitlements. Requirements and behavior: * The policy must have `exceptionsAllowed=true`. * A comment or reason is required. * The exemption records the user ID, policy ID, entitlement type (`ROLE`, `GROUP`, `RESOURCE`, `ORGANIZATION`), entitlement ID, timestamp, and the ID of the user who granted the exemption. * Exempted entitlements are excluded from future violation evaluations for that user. Exemptions can be queried per user via the service to support auditing. Audit action generated: logged with user ID, policy ID, entitlement details, and comment. ### Reports Base URL: `/rest/api/sod-policy-report` | Endpoint | Method | Description | | ------------------------------------------------- | ------ | ---------------------------------------------- | | `/rest/api/sod-policy-report/search` | GET | List generated reports. Params: `from`, `size` | | `/rest/api/sod-policy-report/generate` | POST | Kick off a background report generation job | | `/rest/api/sod-policy-report/download/{fileName}` | GET | Download a generated report as a CSV file | *** --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs-beta.openiam.com/segregation-of-duties/api-endpoints-reference.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.