Edit Role

Modify an existing role definition in RSA Governance & Lifecycle.

POST https://instance.securid.com/aveksa/command.submit?cmd=editRole&roleId=2001

Purpose

The editRole command modifies an existing role definition in the system. It fetches the latest version of the specified role and applies the supplied changes. The modified role enters a pending state and requires the commitRole command to transition into a committed state.

Only users with appropriate permissions (role owner, backup owner, or administrators with role edit entitlements) can execute this command.

Request

Parameters (URL Query)

Parameter	Type	Requirement	Description
cmd	string	Required	Command name: editRole.
roleId	integer	Required	The ID of the role to update. Must be passed as a URL query parameter, not in the request body.
format	string	Optional	The response format: properties: (Default) Key-value format (key=value). If multiple objects return, values are comma-separated. json: JavaScript Object Notation format. Suitable for programmatic parsing.
token	string	Deprecated	Session token retrieved from loginUser. Deprecated. Use the Authorization request header instead.

Request Headers

Header	Type	Requirement	Description
Authorization	string	Required	Bearer token for a user with system administrator privileges, obtained via loginUser. Format: Bearer <token>.
Content-Type	string	Required	Must be application/json.
Accept	string	Optional	Desired response MIME type (for example, application/json or text/plain).

note

The Authorization request header replaces the deprecated token URL query parameter.

Token Type Requirement

Role management commands currently require an authenticated user session token obtained via loginUser with the Role Administrator capability. While the Web Services Administration console allows mapping Role commands to a Trusted Application, requests using a Trusted Application token (loginTrustedApp) currently return HTTP 403 (Not authorized to edit role).

Request Body (JSON)

The request body must contain a JSON object with the role fields to update.

important

• Do not include roleId in the JSON body. It must be passed as a URL query parameter.
• Do not include roleRawName in the JSON body. Role raw names are immutable and cannot be modified during edit operations.

Field	Type	Requirement	Description
roleName	string	Required	Display name of the role. Maximum 256 characters.
longDescription	string	Required	Detailed description of the role. Maximum 4000 characters.
roleSetId	integer	Required	ID of the role set to which this role belongs. Must be a valid existing role set ID.
availableForRequest	integer	Required	Indicates whether the role is available for user requests: 1 (yes) or 0 (no).
shortDescription	string	Optional	Short summary describing the role. Maximum 256 characters.
helpLink	string	Optional	URL pointing to help documentation for the role (e.g., https://help.example.com/role). Maximum 256 characters.
owner	integer	Optional	User ID of the primary owner. If omitted, no owner is assigned.
backupOwner	integer	Optional	User ID of the backup owner. If omitted, no backup owner is assigned.
disabled	boolean	Optional	Whether the role is disabled: true (disabled) or false (enabled).
roleType	string	Optional	Role type code. Acceptable values: "GR" (Global Role), "TR" (Technical Role), or "BR" (Business Role). Defaults to "BR" if null or omitted.

Request Payload Example

{
  "roleName": "Senior Financial Auditor",
  "longDescription": "Grants elevated read and supervisory audit review access across financial modules.",
  "shortDescription": "Senior financial auditing business role",
  "helpLink": "https://help.example.com/roles/senior-auditor",
  "availableForRequest": 1,
  "owner": 1001,
  "backupOwner": 1002,
  "disabled": false,
  "roleSetId": 101,
  "roleType": "BR"
}

Response

Parameters

Parameter	Type	Description
roleVersionId	integer	Version ID of the updated role in pending state. Required when calling commitRole.
status	string	Execution result: success or failure.
message	string	Optional diagnostic or informational details regarding the operation.

Examples

Request

Curl

curl -X POST \
  "https://instance.securid.com/aveksa/command.submit?cmd=editRole&roleId=2001&format=json" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "roleName": "Senior Financial Auditor",
    "longDescription": "Grants elevated read and supervisory audit review access across financial modules.",
    "shortDescription": "Senior financial auditing business role",
    "helpLink": "https://help.example.com/roles/senior-auditor",
    "availableForRequest": 1,
    "owner": 1001,
    "backupOwner": 1002,
    "disabled": false,
    "roleSetId": 101,
    "roleType": "BR"
  }'

Python

import requests

url = "https://instance.securid.com/aveksa/command.submit"
params = {
    "cmd": "editRole",
    "roleId": 2001,
    "format": "json"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json",
    "Accept": "application/json"
}
payload = {
    "roleName": "Senior Financial Auditor",
    "longDescription": "Grants elevated read and supervisory audit review access across financial modules.",
    "shortDescription": "Senior financial auditing business role",
    "helpLink": "https://help.example.com/roles/senior-auditor",
    "availableForRequest": 1,
    "owner": 1001,
    "backupOwner": 1002,
    "disabled": False,
    "roleSetId": 101,
    "roleType": "BR"
}

response = requests.post(url, params=params, headers=headers, json=payload)
if response.status_code == 200:
    print(response.json())
else:
    print(f"Request failed: {response.status_code} - {response.text}")

Node.js

const axios = require('axios');

const url = "https://instance.securid.com/aveksa/command.submit";
const params = {
  cmd: 'editRole',
  roleId: 2001,
  format: 'json'
};
const headers = {
  Authorization: 'Bearer <token>',
  'Content-Type': 'application/json',
  Accept: 'application/json'
};
const payload = {
  roleName: 'Senior Financial Auditor',
  longDescription: 'Grants elevated read and supervisory audit review access across financial modules.',
  shortDescription: 'Senior financial auditing business role',
  helpLink: 'https://help.example.com/roles/senior-auditor',
  availableForRequest: 1,
  owner: 1001,
  backupOwner: 1002,
  disabled: false,
  roleSetId: 101,
  roleType: 'BR'
};

axios.post(url, payload, { params, headers })
  .then(response => {
    console.log(response.data);
  })
  .catch(error => {
    console.error('Request failed:', error.response ? error.response.data : error.message);
  });

PowerShell

$uri = "https://instance.securid.com/aveksa/command.submit?cmd=editRole&roleId=2001&format=json"
$headers = @{
    "Authorization" = "Bearer <token>"
    "Content-Type"  = "application/json"
    "Accept"        = "application/json"
}
$body = @{
    roleName            = "Senior Financial Auditor"
    longDescription     = "Grants elevated read and supervisory audit review access across financial modules."
    shortDescription    = "Senior financial auditing business role"
    helpLink            = "https://help.example.com/roles/senior-auditor"
    availableForRequest = 1
    owner               = 1001
    backupOwner         = 1002
    disabled            = $false
    roleSetId           = 101
    roleType            = "BR"
} | ConvertTo-Json

$response = Invoke-RestMethod -Uri $uri -Method Post -Headers $headers -Body $body
$response

Response

200 OK

JSON Format (format=json):

{
  "status": "success",
  "roleVersionId": 5013,
  "message": "Role 2001 updated successfully in pending state."
}

Properties Format (format=properties):

status=success
roleVersionId=5013
message=Role 2001 updated successfully in pending state.

401 Unauthorized

Missing Token:

<html>
    <head><title>Error</title></head>
    <body>The token is required for the command 'editRole'</body>
</html>

Invalid or Expired Token:

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

403 Forbidden

Returned when calling with a Trusted Application token without user delegation, or when the user lacks role editing permissions:

<html>
    <head><title>Error</title></head>
    <body>Not authorized to edit role.
 Query String=cmd=editRole&amp;roleId=2001&amp;format=json</body>
</html>

404 Not Found

<html>
    <head><title>Error</title></head>
    <body>The role with ID 2001 could not be found.</body>
</html>

412 Precondition Failed

<html>
    <head><title>Error</title></head>
    <body>The parameter roleId is required and must be a valid integer.</body>
</html>

Verified with RSA Governance & Lifecycle version 8.0.0.

References

• Commit Role: Commit pending changes to make the updated role active
• Create Role: Create a new role definition
• Get Role Version: Retrieve current role definition and version details
• RFC 6750: OAuth 2.0 Bearer Token Usage
• RFC 7235: Hypertext Transfer Protocol (HTTP/1.1) Authentication