Web Services API Reference

RSA G&L 8.0+82 CommandsJSON & XMLBearer Token

The RSA Governance & Lifecycle Web Services API exposes identity governance operations, certification reviews, collections, and administrative tasks as parameterized HTTP commands. Every command executes against a unified endpoint distinguished by the cmd query parameter.

POST / GET https://<instance-host>/aveksa/command.submit?cmd=<command>&format=json

Browse API Modules ↓Setup & Quickstart ↓Response Formats ↓Troubleshooting ↓

API Modules

Browse the Web Services API commands organized across 9 functional modules:

🔑

4 endpoints

Authentication

Establish trusted application sessions, perform user logins, fetch login instructions, and terminate sessions.

Information

Fast lookups and search across users, accounts, applications, entitlements, roles, and groups.

Admin

Query system and server information, configure logos, manage security parameters, and import metadata.

Collection

Trigger account and entitlement collection runs, query collector run states, and stop active jobs.

Request

Create access requests, evaluate approvals, fetch change activity states, and cancel in-flight requests.

Review

Launch certification campaigns, evaluate review coverage, monitor progress, and complete reviews.

Roles

Create, edit, version, and delete roles, add or remove group memberships, and commit role definitions.

Rules

Execute governance and compliance rules on demand and trigger scheduled rule processing jobs.

Reporting

Trigger asynchronous report generation and retrieve formatted report output programmatically.

GET

View Endpoints →

High-Level Architecture Flow

Setup and Quickstart

Complete the following configuration steps before invoking API commands.

Step 1: Enable Web Services

Web services are disabled by default. An administrator must enable them before any API call will succeed.

Log in to RSA G&L as an administrator.
Navigate to Admin → Web Services.
Locate Web Services Interface (shows current state: On or Off).
Click Edit, set Web Services Interface to On, and click OK.

Interface Disabled

All API calls to a server with web services disabled return HTTP 403 Unauthorized, regardless of credentials.

Step 2: Configure Client IP Allowlist

The server validates the source IP address of every inbound request against an allowlist. Requests from unlisted addresses are rejected with HTTP 403.

Navigate to Admin → Web Services.
Under Allowed Addresses, click Add.
Enter the client IP address or CIDR subnet (for example, 192.168.1.50 or 10.0.0.0/24).
Click OK.

Add the IP address of every calling application server or developer machine. Keep this allowlist restricted to authorized systems.

Step 3: Register a Trusted Application

A Trusted Application authenticates automated background services without requiring interactive user credentials. It is the recommended method for server-to-server integration.

Navigate to Admin → Web Services → Trusted Application.
Click Add.
Enter a descriptive application name and specify the Concurrent Session Limit.
Click OK.
Copy the generated Client ID and Client Secret. The Client Secret is displayed only once.

Store these credentials securely in your password vault.

Session Limit Exceeded

Each call to loginTrustedApp creates a new session. Exceeding the concurrent session limit returns:

Concurrent session limit exceeded for this trusted application

Cache the Bearer token and reuse it across requests. Re-authenticate only when an API call returns HTTP 401.

Step 4: Verify User Permissions

Permissions enforced on each API call correspond to the user specified in auth-user-id. That user must hold the required privilege for the target command:

Operation Type	Required Privilege	Example Commands
Read Operations	View access to the target object	`findUsers`, `findAccounts`, `getRunStatus`
Change Requests	`System:RequestAccess`	`createChangeRequest`, `cancelChangeRequest`
Approvals & Work Items	Reviewer role or `System:Manage`	`performApproval`, `performWorkItem`
Administrative Actions	`System:Manage`	`collectAccounts`, `processRule`, `importMetadata`

Use a dedicated service account with least-privilege permissions for programmatic integrations.

Step 5: Authenticate and Retrieve Token

Invoke loginTrustedApp to obtain a Bearer token. Pass the Client ID and Client Secret in request headers.

cURL
Python
JavaScript

curl -X POST \
  "https://<instance-host>/aveksa/command.submit?cmd=loginTrustedApp&format=json" \
  -H "ClientId: <client-id>" \
  -H "ClientSecret: <client-secret>" \
  -H "Content-Type: application/json"

import requests

url = "https://<instance-host>/aveksa/command.submit"
params = {
    "cmd": "loginTrustedApp",
    "format": "json"
}
headers = {
    "ClientId": "<client-id>",
    "ClientSecret": "<client-secret>",
    "Content-Type": "application/json"
}

response = requests.post(url, params=params, headers=headers)
token = response.json()["token"]
print(f"Bearer Token: {token}")

const url = "https://<instance-host>/aveksa/command.submit?cmd=loginTrustedApp&format=json";

const response = await fetch(url, {
  method: "POST",
  headers: {
    "ClientId": "<client-id>",
    "ClientSecret": "<client-secret>",
    "Content-Type": "application/json"
  }
});

const data = await response.json();
console.log("Bearer Token:", data.token);

Example JSON Response:

{
  "token": "ta31012485e36e3be2c9:-28aff589:18a2295240d:-7bcd0.529824866054087"
}

Include this token in the Authorization header on all subsequent API requests:

Authorization: Bearer ta31012485e36e3be2c9:-28aff589:18a2295240d:-7bcd0.529824866054087

For interactive user flows, use Login User. Tokens generated by loginUser carry that user's permissions directly, so auth-user-id is not required.

Command Structure

All requests target the unified command servlet:

https://<instance-host>/aveksa/command.submit?cmd=<command>&format=json&<params>

Parameter	Required	Description
`cmd`	Yes	Target command name (for example, `getChangeRequestStatus`).
`format`	No	Response format: `json` or `xml` (default). Use `json` for programmatic access.
`auth-user-id`	Conditional	Required when using a trusted application token for commands executed on behalf of a user.
`token`	No	Legacy token parameter (deprecated). Use the `Authorization: Bearer <token>` header instead.

Commands creating or modifying resources use POST with an XML or JSON body. Read commands use GET.

Responses and Error Handling

All commands return standard HTTP status codes:

Status Code	Meaning	Recommended Action
`200 OK`	Success	Parse response body.
`401 Unauthorized`	Token invalid or expired	Re-authenticate via `loginTrustedApp` and retry with new token.
`403 Forbidden`	Access denied	Verify Web Services are enabled and client IP is on the allowlist.
`404 Not Found`	Resource not found	Verify resource identifier or name passed in the request.
`409 Conflict`	Conflicting state	Inspect active locks or retry with adjusted conflict parameters.
`412 Precondition Failed`	Parameter error	Correct request parameters or payload formatting.
`500 Server Error`	Execution failure	Check server logs (`aveksaServer.log`) and body structure.

Structured Error Responses

By default, unhandled error responses return an HTML document. Enable CustomizeWebServiceErrorResponse under Admin → Web Services → Settings to receive structured JSON or XML error payloads:

{
  "Error": "Password vault profile not found.\n Query String=cmd=notifyVaultPasswordChange&format=json"
}

Output Format Matrix:

`CustomizeWebServiceErrorResponse`	`format` parameter	Success Response	Error Response
`true`	`json`	JSON	JSON
`true`	`xml`	XML	XML
`true`	not provided	XML	XML
`false`	`json`	JSON	HTML
`false`	`xml`	XML	XML

Import Directory Configuration

Commands that import files require a server-side staging directory to be defined:

Navigate to Admin → Web Services.
Under Import Directory, enter the absolute path to the directory on the RSA G&L server.
Click OK.

Place target import archives in this directory before calling file-based import commands.

Troubleshooting

HTTP 403 Forbidden on All Requests

Root Cause: Web services interface is disabled globally, or the client IP address is not registered in the trusted allowlist.
Resolution:
1. Navigate to Admin → Web Services and verify Web Services Interface is set to On.
2. Under Allowed Addresses, verify that the client IP address or CIDR subnet is present in the allowlist.

Root Cause: Invalid Client ID or Client Secret passed in the authentication request.
Resolution: Regenerate credentials under Admin → Web Services → Trusted Application and ensure they match the request headers.

Concurrent Session Limit Exceeded

Root Cause: loginTrustedApp was invoked repeatedly without reusing the cached token, exhausting the concurrent session limit.
Resolution:
1. Cache the Bearer token after initial login and reuse it across requests.
2. Re-authenticate only when an API call returns HTTP 401.

Missing Parameter auth-user-id

Root Cause: A trusted application token was used on a command that acts on behalf of a user, but auth-user-id was omitted from the query string.
Resolution: Append &auth-user-id=<userId> to the request URL.

HTTP 412 Precondition Failed with format=json

Root Cause: The invoked command does not support JSON output on your server version (fixed for all commands as of 8.1.0).
Resolution: Remove &format=json or set format=xml for legacy commands.

Invalid Attribute Name Error

Root Cause: An attribute name in the request payload does not exist in the server-side configuration schema.
Resolution: Inspect aveksa-plug-ins.xml on the RSA G&L server to verify valid attribute definitions.

Empty HTTP 200 Response Body

Root Cause: The operation succeeded, but the specific command returns an empty response payload by design.
Resolution: Verify that the HTTP response code is 200 OK. Commands such as cancelChangeRequest do not return payload content on success.

HTTP 403 on Role Commands with Trusted Application Token

Root Cause: Product limitation where backend role management services require an interactive user session token (loginUser) with the Role Administrator capability, returning authorization errors when invoked with a Trusted Application token.
Resolution: Obtain a user session token via loginUser using an administrator account, and supply that token in the Authorization: Bearer <token> header for Role commands (createRole, editRole, deleteRole, getRoleVersion, addGroupToRole, removeGroupFromRole, commitRole).

References

RSA Governance & Lifecycle Documentation

RSA Governance & Lifecycle Web Services API Guide: Endpoint specifications, schema definitions, and administrative settings.
RSA Governance & Lifecycle Administration Guide: Web services enablement, IP allowlists, and trusted application setup.

HTTP & Security Standards

RFC 7235: HTTP/1.1 Authentication: Authentication framework and HTTP 401/403 status codes.
RFC 6750: OAuth 2.0 Bearer Token Usage: Bearer token authorization header format and security requirements.

API Modules​

Authentication

Information

Admin

Collection

Request

Review

Roles

Rules

Reporting

High-Level Architecture Flow​

Setup and Quickstart​

Step 1: Enable Web Services​

Step 2: Configure Client IP Allowlist​

Step 3: Register a Trusted Application​

Step 4: Verify User Permissions​

Step 5: Authenticate and Retrieve Token​

Command Structure​

Responses and Error Handling​

Structured Error Responses​

Import Directory Configuration​

Troubleshooting​

HTTP 403 Forbidden on All Requests​

HTTP 401 Unauthorized Immediately After Login​

Concurrent Session Limit Exceeded​

Missing Parameter auth-user-id​

HTTP 412 Precondition Failed with format=json​

Invalid Attribute Name Error​

Empty HTTP 200 Response Body​

HTTP 403 on Role Commands with Trusted Application Token​

References​

API Modules

High-Level Architecture Flow

Setup and Quickstart

Step 1: Enable Web Services

Step 2: Configure Client IP Allowlist

Step 3: Register a Trusted Application

Step 4: Verify User Permissions

Step 5: Authenticate and Retrieve Token

Command Structure

Responses and Error Handling

Structured Error Responses

Import Directory Configuration

Troubleshooting

HTTP 403 Forbidden on All Requests

HTTP 401 Unauthorized Immediately After Login

Concurrent Session Limit Exceeded

Missing Parameter auth-user-id

HTTP 412 Precondition Failed with format=json

Invalid Attribute Name Error

Empty HTTP 200 Response Body

HTTP 403 on Role Commands with Trusted Application Token

References