API Reference Guide

The RSA Governance & Lifecycle Web Services API exposes identity operations as HTTP commands. Use it to automate collections, trigger reviews, manage change requests, and run governance rules from any HTTP client, script, or pipeline.

All commands share a single endpoint. The operation is selected with the cmd query parameter.

GET / POST https://instance.securid.com/aveksa/command.submit?cmd=<command>

High-Level Flow

Step 1: Enable Web Services

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

Log in as an administrator.
Go to Admin > Web Services. The Web Services Interface field shows the current state (On/Off).
Click Edit, set Web Services Interface to On, and click OK.

warning

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

Step 2: Control Access

The server validates the source IP address of every request against an allowlist. Requests from addresses not on the list are rejected with 403.

Go to Admin > Web Services.
Under Allowed Addresses, click Add.
Enter an IP address or CIDR range (for example 192.168.1.50 or 10.0.0.0/24).
Click OK.

Add the IP of every server or developer machine that will call the API. Keep this list as small as possible.

Step 3: Trusted Application

A Trusted Application authenticates a calling system without requiring a user's credentials. It is the recommended method for server-to-server integration.

Go to Admin > Web Services > Trusted Application.
Click Add.
Enter a name and set the Concurrent Session Limit.
Click OK. The Client ID and Client Secret are shown.
Copy both values. The Client Secret is shown only once.

Store the credentials securely. They are passed as request headers to Login as Trusted Application.

Session Limit

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

Concurrent session limit exceeded for this trusted application

Cache the token and reuse it. Re-authenticate only when the server returns 401.

Step 4: Permissions

The permissions enforced on each API call are those of the user specified in auth-user-id. That user must hold the required privilege for each command being called.

Type of operation	Required privilege
Read operations (find, get, status checks)	View access to the relevant data
Create and cancel change requests	System:RequestAccess or equivalent
Approve or perform work items	Reviewer role or System:Manage
Admin operations (rules, roles, collections, attributes)	System:Manage

Use a dedicated service account with the minimum privileges needed for the integration. Avoid using personal administrator accounts.

Step 5: Authenticate

Call loginTrustedApp to get a Bearer token. Pass the Client ID and Client Secret as request headers.

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

Response:

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

Pass this token in the Authorization header of every subsequent request:

Authorization: Bearer <token>

See Login as Trusted Application for the full reference.

For browser-based or user-initiated flows, use Login User instead. The token from loginUser carries that user's permissions directly, so auth-user-id is not needed.

Command Structure

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

Parameter	Required	Description
`cmd`	Yes	Command name, for example `getChangeRequestStatus`
`format`	No	`xml` (default) or `json`. Use `json` for all programmatic access
`auth-user-id`	Conditional	Required for trusted application tokens on commands that act on behalf of a user
`token`	No	Deprecated. Use the `Authorization` header instead

Commands that create or update data use POST with an XML body. Read commands use GET.

note

A small number of commands do not support format=json. For example, cancelChangeRequest returns 412 if format=json is included. Check the individual command reference for format limitations.

Responses and Error Handling

All commands return standard HTTP status codes.

Code	Meaning	Action
`200`	Success	Parse the response body
`401`	Token invalid or expired	Re-authenticate and retry with a new token
`403`	Forbidden	Check that web services are enabled and the client IP is in the allowlist
`404`	Resource not found	Verify the ID or name passed in the request
`409`	Conflict	Adjust `failOnViolation` or `failOnOutstanding` and retry
`412`	Missing or invalid parameter	Fix the request parameters or body
`500`	Server error or malformed body	Check the request body format, XML root element, and encoding

Error responses are returned as HTML regardless of the format parameter:

<html>
    <head><title>Error</title></head>
    <body>The parameter id is required.
 Query String=cmd=cancelChangeActivity&format=json</body>
</html>

The Query String line in the body echoes back the actual request parameters, which is useful for diagnosing missing or malformed values.

API Categories

Category	Description
Authentication	Login, logout, trusted application sessions
Admin	Server info, security settings, logo, images, metadata import
Information	Search accounts, applications, entitlements, roles, and more
Collection	Trigger and manage identity data collection runs
Request	Create, approve, and cancel change requests
Review	Launch reviews, update coverage, manage review statuses
Roles	Add and remove groups from roles, commit role definitions
Rules	Execute and schedule governance rules
Reporting	Generate and retrieve reports

Import Directory

Commands that import data require a server-side directory to be configured first.

Go to Admin > Web Services.
Under Import Directory, enter the full path to the directory on the server.
Click OK.

Place the import file in this directory before calling the import command.

Troubleshooting

Symptom	Likely cause	Fix
`403` on all requests	Web services disabled, or client IP not in allowlist	Enable web services; add client IP to allowlist
`401` immediately after login	Client ID or Secret incorrect	Regenerate credentials in Admin > Web Services > Trusted Application
`Concurrent session limit exceeded`	`loginTrustedApp` called too frequently	Cache the token; re-authenticate only on `401`
`The parameter auth-user-id is required`	Trusted app token used without `auth-user-id`	Add `&auth-user-id=<userId>` to the request
`412` with `format=json`	Command does not support JSON format	Remove `format=json` from the request
`invalid attribute name 'X'`	Attribute name not in server configuration	Check `aveksa-plug-ins.xml` on the server for valid external attribute names
Empty 200 body	Command succeeded with no output	Normal for commands such as `cancelChangeRequest`

High-Level Flow​

Step 1: Enable Web Services​

Step 2: Control Access​

Step 3: Trusted Application​

Step 4: Permissions​

Step 5: Authenticate​

Command Structure​

Responses and Error Handling​

API Categories​

Import Directory​

Troubleshooting​