Get Role Version

Retrieve the latest role version details and configuration state in RSA Governance & Lifecycle.

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

Purpose

The getRoleVersion command retrieves the latest details and metadata for a specific Role. If a pending role version exists, the command returns the attributes of that pending version (for example, in a New or Changed state). If no pending version exists, it returns the current committed state of the role (roleVersionId will be null).

Parameters are passed as URL query parameters using an HTTP POST request.

Request

Parameters (URL Query)

Parameter	Type	Requirement	Description
cmd	string	Required	Command name: getRoleVersion.
roleId	integer	Required	The ID of the role to retrieve. Must be a valid integer.
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 obtained via loginUser. Format: Bearer <token>.
Accept	string	Optional	Desired response MIME type (for example, application/json or text/plain).
Content-Type	string	Optional	Content type header: application/x-www-form-urlencoded or application/json.

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 view role version).

Response

Parameters

Parameter	Type	Description
id	integer	Unique ID of the requested role.
roleVersionId	integer	Version ID of the role version (null if role is in a committed state).
roleName	string	Display name of the role.
roleRawName	string	Unique raw identifier of the role.
longDescription	string	Detailed description of the role.
shortDescription	string	Short summary of the role.
helpLink	string	Help URL configured for the role.
availableForRequest	integer	Indicates whether the role is requestable: 1 (yes) or 0 (no).
owner	integer	User ID of the primary owner.
backupOwner	integer	User ID of the backup owner.
disabled	boolean	Indicates whether the role is disabled: true or false.
roleSetId	integer	Role set ID mapped to this role version.
roleType	string	Role type code: "GR" (Global Role), "TR" (Technical Role), or "BR" (Business Role).
state	string	Current state of the role version (e.g., "Committed", "New", "Changed").
createdBy	integer	User ID of the user who created this role version.
creationDate	string	Timestamp when this role version was created (format: yyyy-MM-dd HH:mm:ss.S).

Examples

Request

Curl

curl -X POST \
  "https://instance.securid.com/aveksa/command.submit?cmd=getRoleVersion&roleId=2001&format=json" \
  -H "Authorization: Bearer <token>" \
  -H "Accept: application/json"

Python

import requests

url = "https://instance.securid.com/aveksa/command.submit"
params = {
    "cmd": "getRoleVersion",
    "roleId": 2001,
    "format": "json"
}
headers = {
    "Authorization": "Bearer <token>",
    "Accept": "application/json"
}

response = requests.post(url, params=params, headers=headers)
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: 'getRoleVersion',
  roleId: 2001,
  format: 'json'
};
const headers = {
  Authorization: 'Bearer <token>',
  Accept: 'application/json'
};

axios.post(url, null, { 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=getRoleVersion&roleId=2001&format=json"
$headers = @{
    "Authorization" = "Bearer <token>"
    "Accept"        = "application/json"
}

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

Response

200 OK

JSON Format (format=json):

{
  "id": 2001,
  "roleVersionId": 5013,
  "roleName": "Senior Financial Auditor",
  "roleRawName": "ROLE_FIN_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",
  "state": "Changed",
  "createdBy": 1001,
  "creationDate": "2026-03-15 14:22:10.0"
}

Properties Format (format=properties):

id=2001
roleVersionId=5013
roleName=Senior Financial Auditor
roleRawName=ROLE_FIN_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
state=Changed
createdBy=1001
creationDate=2026-03-15 14:22:10.0

401 Unauthorized

Missing Token:

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

Invalid or Expired Token:

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

403 Forbidden

Returned when calling with a Trusted Application token without user delegation, or when the user is not a Role Administrator, owner, or backup owner:

<html>
    <head><title>Error</title></head>
    <body>Not authorized to view role version. User must be the owner, backup owner, or a Role Administrator.
 Query String=cmd=getRoleVersion&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

• Edit Role: Modify role definition attributes
• Commit Role: Commit pending changes to a role
• Create Role: Create a new role definition
• RFC 6750: OAuth 2.0 Bearer Token Usage
• RFC 7235: Hypertext Transfer Protocol (HTTP/1.1) Authentication