Create Change Request

Create a change request describing one or more identity changes to submit for approval and fulfillment.

POST https://instance.securid.com/aveksa/command.submit?cmd=createChangeRequest

note

This command requires an HTTP POST request. The request body must be a valid XML document describing the changes. Set Content-Type: application/xml.

Supported Change Types

User Changes

• Add / Remove entitlement for a user
• Add / Remove user to/from an application role
• Add / Remove user to/from a group
• Add / Remove user to/from a global role
• Register a user
• Terminate a user
• Out of Office / Return to Office

Account Changes

• Create / Delete account
• Enable / Disable account
• Lock / Unlock account
• Add / Remove account to/from a group
• Add / Remove entitlement for an account
• Add / Remove application role for an account
• Map / Unmap user to/from an account
• Reset / Synchronize password for an account

Request

Parameters

command	createChangeRequest
auth-user-id	The ID of the user submitting the request. Required when using a trusted application token. Not used with user tokens.
failOnViolation	If true, the request is blocked and returns a 409 when the proposed changes would create policy violations. Default: true. Set to false to submit despite violations.
failOnOutstanding	If true, the request is blocked and returns a 409 when there are already outstanding change requests for the same changes. Default: true. Set to false to submit despite outstanding requests.
format	xml - (Default) Returns output as XML. json - Useful for parsing into JavaScript or other languages. See www.json.org for details.
token	Deprecated. Use the Authorization request header instead.

Headers

Authorization	Bearer token
Content-Type	application/xml
Accept	application/json

Body

The request body is an XML document with a <Changes> root element containing one or more <UserChange> and/or <AccountChange> elements. Multiple changes can be submitted in a single request.

<Changes>
  <Description>Optional description</Description>
  <Notes>Optional notes</Notes>
  <FulfillmentDate>dd-MMM-yyyy</FulfillmentDate>
  <RevocationDate>dd-MMM-yyyy</RevocationDate>
  <OnBehalfOf>userId</OnBehalfOf>
  <Parameters>
    <Parameter scope="public">
      <Name>paramName</Name>
      <Value>paramValue</Value>
    </Parameter>
  </Parameters>
  <UserChange>...</UserChange>
  <AccountChange>...</AccountChange>
</Changes>

Wrapper Elements

Description	Optional description for the change request. 0 or 1 element.
Notes	Optional notes for the change request. 0 or 1 element.
FulfillmentDate	Date the change should be fulfilled. Format: dd-MMM-yyyy (e.g. 20-Jun-2026). 0 or 1 element.
RevocationDate	Date the change should be revoked. Format: dd-MMM-yyyy. 0 or 1 element.
OnBehalfOf	User ID of the user to submit the request on behalf of. The calling user must be authorized for on-behalf-of submissions. 0 or 1 element.
Parameters	Additional name/value pairs passed to the request, similar to variables from a request form. Contains 0 or more Parameter elements. Each Parameter has an optional scope attribute: public (default; visible to end users, passed to workflow), job (passed to workflow, not shown to end users), or private (not passed to workflow or end users).

Batch behavior

A single request body can contain multiple <UserChange> and <AccountChange> elements. If any change is invalid, the entire request fails with a 412. All changes must be valid for the request to proceed.

User Change Operations

Each <UserChange> element must include an <Operation> element. The required elements vary by operation.

Add / Remove entitlement for a user

<!-- Add entitlement -->
<UserChange>
  <Operation>Add</Operation>
  <User>userId</User>
  <BusinessSource>businessSourceName</BusinessSource>
  <Resource>resourceName</Resource>
  <Action>actionName</Action>
</UserChange>

<!-- Remove entitlement -->
<UserChange>
  <Operation>Remove</Operation>
  <User>userId</User>
  <BusinessSource>businessSourceName</BusinessSource>
  <Resource>resourceName</Resource>
  <Action>actionName</Action>
</UserChange>

Resource and Action together identify the entitlement. Use Find Entitlements to retrieve valid values.

Add / Remove user to/from an application role

<!-- Add to application role -->
<UserChange>
  <Operation>Add</Operation>
  <User>userId</User>
  <BusinessSource>businessSourceName</BusinessSource>
  <ApplicationRole>applicationRoleName</ApplicationRole>
</UserChange>

<!-- Remove from application role -->
<UserChange>
  <Operation>Remove</Operation>
  <User>userId</User>
  <BusinessSource>businessSourceName</BusinessSource>
  <ApplicationRole>applicationRoleName</ApplicationRole>
</UserChange>

Add / Remove user to/from a group

<!-- Add to group -->
<UserChange>
  <Operation>Add</Operation>
  <User>userId</User>
  <BusinessSource>businessSourceName</BusinessSource>
  <Group>groupName</Group>
</UserChange>

<!-- Remove from group -->
<UserChange>
  <Operation>Remove</Operation>
  <User>userId</User>
  <BusinessSource>businessSourceName</BusinessSource>
  <Group>groupName</Group>
</UserChange>

Add / Remove user to/from a global role

<!-- Add to global role -->
<UserChange>
  <Operation>Add</Operation>
  <User>userId</User>
  <GlobalRole>globalRoleName</GlobalRole>
  <GlobalRoleSet>globalRoleSetName</GlobalRoleSet>
</UserChange>

<!-- Remove from global role -->
<UserChange>
  <Operation>Remove</Operation>
  <User>userId</User>
  <GlobalRole>globalRoleName</GlobalRole>
  <GlobalRoleSet>globalRoleSetName</GlobalRoleSet>
</UserChange>

GlobalRole and GlobalRoleSet are used together to identify the global role. No BusinessSource is needed.

Register a user

<UserChange>
  <Operation>Register</Operation>
  <BusinessSource>businessSourceName</BusinessSource>
  <Account>accountName</Account>
  <Parameters>
    <Parameter>
      <Name>RUq_NotificationEmail</Name>
      <Value>user@example.com</Value>
    </Parameter>
    <Parameter>
      <!-- Auto-generate email using a Naming Policy -->
      <Name>mail</Name>
      <Value>#GENERATED:PolicyName=myPolicy:fname=firstName:lname=lastName#@example.com</Value>
    </Parameter>
    <Parameter>
      <!-- Auto-generate password using a Password Policy -->
      <Name>Password</Name>
      <Value>${GeneratedPassword}</Value>
    </Parameter>
    <Parameter>
      <Name>additionalParamName</Name>
      <Value>additionalParamValue</Value>
    </Parameter>
  </Parameters>
</UserChange>

• Account must be the name of the account. The request does not complete until an account with this name is collected.
• The Parameters element is required and must contain one or more Parameter elements corresponding to the Create Account input parameters for the business source.
• RUq_NotificationEmail sends the new account ID and password to the specified address on completion.
• ${GeneratedPassword} auto-generates a password if a Password Policy is associated with the business source.
• The email auto-generation #GENERATED:...# pattern only works if a Naming Policy is configured and associated with the business source.

Terminate a user

<UserChange>
  <Operation>Terminate</Operation>
  <User>userId</User>
  <Parameters>
    <Parameter>
      <Name>ActionOnMappedAccounts</Name>
      <Value>Delete</Value>
    </Parameter>
    <Parameter>
      <Name>ActionOnSharedAccount</Name>
      <Value>Disable</Value>
    </Parameter>
    <Parameter>
      <Name>ActionOnServiceAccount</Name>
      <Value>Disable</Value>
    </Parameter>
    <Parameter>
      <Name>RevokeAllEnts</Name>
      <Value>true</Value>
    </Parameter>
  </Parameters>
</UserChange>

The Parameters element is optional. Valid parameter values:

Parameter	Valid Values
ActionOnMappedAccounts	Delete | Lock | Disable
ActionOnSharedAccount	Disable | Reset
ActionOnServiceAccount	Disable | Reset
RevokeAllEnts	true | false

Out of Office / Return to Office

<!-- Out of Office: include FulfillmentDate and RevocationDate on the Changes wrapper -->
<Changes>
  <FulfillmentDate>20-Jun-2026</FulfillmentDate>
  <RevocationDate>27-Jun-2026</RevocationDate>
  <UserChange>
    <Operation>OutOfOffice</Operation>
    <User>userId</User>
    <Delegate>delegateUserId</Delegate>
  </UserChange>
</Changes>

<!-- Return to Office -->
<Changes>
  <UserChange>
    <Operation>ReturnToOffice</Operation>
    <User>userId</User>
  </UserChange>
</Changes>

• FulfillmentDate on the <Changes> wrapper is the date the user goes out of office. RevocationDate is the date they return.
• Delegate is optional. If specified, must be the user ID of the delegate.

Account Change Operations

Each <AccountChange> element must include an <Operation> element.

Create account

<AccountChange>
  <Operation>Create</Operation>
  <User>userId</User>
  <BusinessSource>businessSourceName</BusinessSource>
</AccountChange>

Delete account

<AccountChange>
  <Operation>Delete</Operation>
  <User>userId</User>
  <BusinessSource>businessSourceName</BusinessSource>
  <Account>accountName</Account>
  <AccountCollector>collectorName</AccountCollector>
</AccountChange>

Enable / Disable account

<!-- Enable -->
<AccountChange>
  <Operation>Enable</Operation>
  <BusinessSource>businessSourceName</BusinessSource>
  <Account>accountName</Account>
</AccountChange>

<!-- Disable -->
<AccountChange>
  <Operation>Disable</Operation>
  <BusinessSource>businessSourceName</BusinessSource>
  <Account>accountName</Account>
</AccountChange>

Lock / Unlock account

<!-- Lock -->
<AccountChange>
  <Operation>Lock</Operation>
  <BusinessSource>businessSourceName</BusinessSource>
  <Account>accountName</Account>
</AccountChange>

<!-- Unlock -->
<AccountChange>
  <Operation>Unlock</Operation>
  <BusinessSource>businessSourceName</BusinessSource>
  <Account>accountName</Account>
</AccountChange>

Add / Remove account to/from a group

Use AccountBusinessSource and GroupBusinessSource (preferred):

<!-- Add account to group -->
<AccountChange>
  <Operation>Add</Operation>
  <Account>accountName</Account>
  <AccountBusinessSource>accountBusinessSourceName</AccountBusinessSource>
  <Group>groupName</Group>
  <GroupBusinessSource>groupBusinessSourceName</GroupBusinessSource>
</AccountChange>

<!-- Remove account from group -->
<AccountChange>
  <Operation>Remove</Operation>
  <Account>accountName</Account>
  <AccountBusinessSource>accountBusinessSourceName</AccountBusinessSource>
  <Group>groupName</Group>
  <GroupBusinessSource>groupBusinessSourceName</GroupBusinessSource>
</AccountChange>

note

AccountCollector and GroupCollector can be used in place of AccountBusinessSource and GroupBusinessSource but are deprecated.

Add / Remove entitlement for an account

<!-- Add entitlement to account -->
<AccountChange>
  <Operation>Add</Operation>
  <Account>accountName</Account>
  <AccountCollector>collectorName</AccountCollector>
  <BusinessSource>businessSourceName</BusinessSource>
  <Resource>resourceName</Resource>
  <Action>actionName</Action>
</AccountChange>

<!-- Remove entitlement from account -->
<AccountChange>
  <Operation>Remove</Operation>
  <Account>accountName</Account>
  <AccountCollector>collectorName</AccountCollector>
  <BusinessSource>businessSourceName</BusinessSource>
  <Resource>resourceName</Resource>
  <Action>actionName</Action>
</AccountChange>

Add / Remove application role for an account

<!-- Add application role to account -->
<AccountChange>
  <Operation>Add</Operation>
  <Account>accountName</Account>
  <AccountCollector>collectorName</AccountCollector>
  <BusinessSource>businessSourceName</BusinessSource>
  <ApplicationRole>applicationRoleName</ApplicationRole>
</AccountChange>

<!-- Remove application role from account -->
<AccountChange>
  <Operation>Remove</Operation>
  <Account>accountName</Account>
  <AccountCollector>collectorName</AccountCollector>
  <BusinessSource>businessSourceName</BusinessSource>
  <ApplicationRole>applicationRoleName</ApplicationRole>
</AccountChange>

Map / Unmap user to/from an account

<!-- Map user to account -->
<AccountChange>
  <Operation>Map</Operation>
  <User>userId</User>
  <Account>accountName</Account>
  <BusinessSource>businessSourceName</BusinessSource>
</AccountChange>

<!-- Unmap user from account -->
<AccountChange>
  <Operation>Unmap</Operation>
  <User>userId</User>
  <Account>accountName</Account>
  <BusinessSource>businessSourceName</BusinessSource>
</AccountChange>

Reset / Synchronize password for an account

warning

Use a secure channel (HTTPS) when submitting passwords. Do not log or store the Password value.

<!-- Reset password: resets the password on the target application and synchronizes if configured -->
<AccountChange>
  <Operation>ResetPassword</Operation>
  <User>userId</User>
  <Account>accountName</Account>
  <BusinessSource>businessSourceName</BusinessSource>
  <Password>newPassword</Password>
</AccountChange>

<!-- Synchronize password: synchronizes the existing password to other accounts without resetting -->
<AccountChange>
  <Operation>SynchronizePassword</Operation>
  <User>userId</User>
  <BusinessSource>businessSourceName</BusinessSource>
  <Password>currentPassword</Password>
</AccountChange>

• ResetPassword resets the account password on the target application. If password synchronization is enabled and the application is configured as the source, the password is also synchronized to other accounts.
• SynchronizePassword synchronizes the current password to other accounts. It does not reset the password on the given application; it assumes the password is already set correctly there.

Custom Attributes

Any <UserChange> or <AccountChange> element can include 0 or more <CustomAttribute> elements to store metadata on the change item:

<UserChange>
  <Operation>Add</Operation>
  <User>userId</User>
  <BusinessSource>businessSourceName</BusinessSource>
  <ApplicationRole>applicationRoleName</ApplicationRole>
  <CustomAttribute name="Justification">Business requirement</CustomAttribute>
  <CustomAttribute name="TicketId">INC-12345</CustomAttribute>
</UserChange>

The name attribute must match the display name of a configured custom attribute. Date values must use the format yyyy-MM-dd HH:mm:ss.

Response

Success (200)

On success, the command returns the new change request ID and name.

Id	The numeric ID of the created change request. Use with Get Change Request Status.
Name	The display name of the change request (e.g. 00251).
type	The workflow type: fulfillment or revocation.

RevocationDate creates two change requests

When <RevocationDate> is set in the <Changes> wrapper (or for Out of Office / Return to Office operations), the server automatically creates a second revocation change request in addition to the fulfillment one. The response Request field becomes an array of two objects instead of a single object. The revocation CR shares the same Name as the fulfillment CR, with the suffix [This is an automatically generated revocation request.].

Conflicts (409)

If failOnOutstanding=true (default) and there are already pending change requests for the same changes, or if failOnViolation=true (default) and the changes would create policy violations, the server returns 409 with details about the conflict.

Set failOnOutstanding=false or failOnViolation=false to bypass the corresponding check and submit the request anyway.

OutstandingRequests	Present when existing pending requests conflict with the proposed changes. The total attribute shows the count of conflicts. Contains the conflicting UserChange or AccountChange elements.
Violations	Present when the proposed changes would create policy violations. Contains violation details.
AdditionalInfoRequired	Present when further input is required before the request can be submitted (for example, submission questions or multiple account templates). The request cannot proceed until the required information is provided through the UI.

Examples

Request

The following example adds a user to an application role using a trusted application token.

Curl

curl -K -X POST \
"https://instance.securid.com/aveksa/command.submit?cmd=createChangeRequest&format=json&auth-user-id=jsmith" \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/xml" \
-d '<Changes>
  <UserChange>
    <Operation>Add</Operation>
    <User>jsmith</User>
    <BusinessSource>BeyondTrust Password Safe</BusinessSource>
    <ApplicationRole>Integrations - Service Accounts</ApplicationRole>
  </UserChange>
</Changes>'

Python

import requests

url = "https://instance.securid.com/aveksa/command.submit"

params = {
    "cmd": "createChangeRequest",
    "format": "json",
    "auth-user-id": "jsmith"
}

headers = {
    'Authorization': 'Bearer <token>',
    'Content-Type': 'application/xml'
}

body = """<Changes>
  <UserChange>
    <Operation>Add</Operation>
    <User>jsmith</User>
    <BusinessSource>BeyondTrust Password Safe</BusinessSource>
    <ApplicationRole>Integrations - Service Accounts</ApplicationRole>
  </UserChange>
</Changes>"""

response = requests.post(url, params=params, headers=headers, data=body)

if response.status_code == 200:
    data = response.json()
    req = data["createChangeRequest"]["Request"]
    print(f"Created change request {req['Name']} (id={req['Id']})")
elif response.status_code == 409:
    print("Blocked by outstanding requests or violations:", response.json())
else:
    print(f"Request failed with status code {response.status_code}")
    print(response.text)

Node.js

const axios = require('axios');

const url = "https://instance.securid.com/aveksa/command.submit";

const params = {
    cmd: "createChangeRequest",
    format: "json",
    "auth-user-id": "jsmith"
};

const headers = {
    'Authorization': 'Bearer <token>',
    'Content-Type': 'application/xml'
};

const body = `<Changes>
  <UserChange>
    <Operation>Add</Operation>
    <User>jsmith</User>
    <BusinessSource>BeyondTrust Password Safe</BusinessSource>
    <ApplicationRole>Integrations - Service Accounts</ApplicationRole>
  </UserChange>
</Changes>`;

axios.post(url, body, { params, headers })
    .then(response => {
        const req = response.data.createChangeRequest.Request;
        console.log(`Created change request ${req.Name} (id=${req.Id})`);
    })
    .catch(error => {
        if (error.response) {
            console.error(`Error ${error.response.status}:`, error.response.data);
        } else {
            console.error('Error:', error.message);
        }
    });

Response

200 Created

Single change request (no RevocationDate):

{
    "createChangeRequest": {
        "Request": {
            "Id": 250,
            "type": "fulfillment",
            "Name": "00251"
        }
    }
}

200 With Revocation

When <RevocationDate> is set, the server creates a fulfillment CR and a revocation CR. The Request field becomes an array:

{
    "createChangeRequest": {
        "Request": [
            {
                "Id": 255,
                "type": "fulfillment",
                "Name": "00260"
            },
            {
                "Id": 256,
                "type": "revocation",
                "Name": "00260[This is an automatically generated revocation request.]"
            }
        ]
    }
}

200 XML Format

Without format=json, the response is XML:

<?xml version="1.0" encoding="UTF-8"?>
<createChangeRequest>
  <Request type="fulfillment">
    <Id>262</Id>
    <Name>00276</Name>
  </Request>
</createChangeRequest>

409 Outstanding Requests

Returned when failOnOutstanding=true (default) and an existing pending request targets the same change. Set failOnOutstanding=false to bypass.

{
    "createChangeRequest": {
        "Request": {
            "OutstandingRequests": {
                "total": 1,
                "UserChange": {
                    "User": "jsmith",
                    "BusinessSource": "BeyondTrust Password Safe",
                    "Operation": "Add",
                    "ApplicationRole": "Integrations - Service Accounts"
                }
            },
            "type": "fulfillment"
        }
    }
}

409 Violations

Returned when failOnViolation=true (default) and the proposed change would create a policy violation. Set failOnViolation=false to bypass.

<?xml version="1.0" encoding="UTF-8"?>
<createChangeRequest>
  <Request type="fulfillment">
    <Violations>
      <Violation>
        <Description>SOD violation description</Description>
      </Violation>
    </Violations>
  </Request>
</createChangeRequest>

401 Invalid Token

<html>
    <head>
        <title>Error</title>
    </head>
    <body>The token is not valid for the command 'createChangeRequest'. Token is invalid or expired</body>
</html>

412 Validation Error

Common validation errors and their messages:

Invalid XML body:

<html>
    <head><title>Error</title></head>
    <body>Invalid XML content in the request body. Premature end of file.
 Query String=cmd=createChangeRequest&amp;format=json</body>
</html>

No changes in body:

<html>
    <head><title>Error</title></head>
    <body>The change request could not be created. No changes were found.
 Query String=cmd=createChangeRequest&amp;format=json</body>
</html>

Missing Operation element:

<html>
    <head><title>Error</title></head>
    <body>The change request could not be created. Operation is required.</body>
</html>

Invalid Operation value:

<html>
    <head><title>Error</title></head>
    <body>The change request could not be created. Invalid operation '&lt;value&gt;'. The valid options are 'Add', 'Remove', 'Terminate', 'OutOfOffice', 'ReturnToOffice', and 'Register'.</body>
</html>

User not found:

<html>
    <head><title>Error</title></head>
    <body>The change request could not be created. Could not retrieve user from the id '&lt;userId&gt;'.</body>
</html>

Business source not found:

<html>
    <head><title>Error</title></head>
    <body>The change request could not be created. The business source named '&lt;name&gt;' could not be retrieved.</body>
</html>

Missing required elements:

<html>
    <head><title>Error</title></head>
    <body>The change request could not be created. User change could not be created. Not all required properties were found.</body>
</html>

Application role not found:

<html>
    <head><title>Error</title></head>
    <body>The change request could not be created. The user could not be added to the application role because the application role could not be retrieved. The application role '&lt;name&gt;' could not be found for business source '&lt;businessSource&gt;'.</body>
</html>

Global role not found:

<html>
    <head><title>Error</title></head>
    <body>The change request could not be created. The user could not be added to the global role because the global role could not be retrieved. The global role '&lt;name&gt;' could not be found for the role set '&lt;roleSet&gt;'.</body>
</html>

Group not found:

<html>
    <head><title>Error</title></head>
    <body>The change request could not be created. The group could not be added to the user because the group could not be retrieved. The group with name '&lt;name&gt;' could not be found for application '&lt;businessSource&gt;'.</body>
</html>

Entitlement not found:

<html>
    <head><title>Error</title></head>
    <body>The change request could not be created. The entitlement could not be added to the user because the entitlement could not be retrieved. The entitlement with resource '&lt;resource&gt;' and action '&lt;action&gt;' could not be found for application '&lt;businessSource&gt;'.</body>
</html>

Account not found (AccountChange):

<html>
    <head><title>Error</title></head>
    <body>The change request could not be created. The account named '&lt;account&gt;' for business source '&lt;businessSource&gt;' could not be retrieved.</body>
</html>

Business source has no account template (Create operation):

<html>
    <head><title>Error</title></head>
    <body>The change request could not be created. The account could not be created because the business source named '&lt;businessSource&gt;' does not have a valid account template.</body>
</html>

Invalid AccountChange operation:

<html>
    <head><title>Error</title></head>
    <body>The change request could not be created. Invalid operation '&lt;value&gt;'. The valid options are 'Create', 'Delete', 'Add', 'Remove', 'ResetPassword', 'SynchronizePassword', 'Lock', 'Unlock', 'Enable', 'Disable', 'Map', 'Unmap'.</body>
</html>

Verified with RSA Governance & Lifecycle version 8.0.0.188886 P10_HF01.

See Also

• Get Change Request Status: Check the status of a change request after it is created
• Cancel Change Request: Cancel a change request that is in progress
• Get Work Items for User: Retrieve pending approvals generated by the change request
• Perform Work Item: Approve or complete a generated work item