OneSpan Sign Developers: Account Role - Part 2

By allowing Enterprise Administrators to define customized roles with certain permissions and assign these roles to your account users, OneSpan Sign “Roles & Permissions” feature delivers a more secured user management solution with improved operational efficiency.

In part 1 of this blog series, we briefly introduced the Roles & Permissions feature and learned how to create an account role. Picking up where we left off, we will continue to showcase the other relative APIs and SDK functions regarding account roles. Without further delay, let’s get started!

Manipulate Account Roles

In order to retrieve all the existing account roles or to query a specific account role by its ID, OneSpan Sign uses the two APIs and SDK functions below:

REST API

HTTP Request

GET /api/account/roles
GET /api/account/roles/{accountRoleId}

HTTP Headers

Authorization: Basic {your_api_key}
Accept: application/json

Java SDK

AccountRole accountRole = eslClient.getAccountService().getAccountRole("account_role_id");
List<AccountRole> accountRoles = eslClient.getAccountService().getAccountRoles();

Given an existing account role, you can update its name, description, and associated permissions with:

REST API

HTTP Request

PUT /api/account/roles/{accountRoleId}

HTTP Headers

Authorization: Basic {your_api_key}
Content-Type: application/json
Accept: application/json

Example Payload

{
  "name": "Updated Account Role Name",
  "enabled": true,
  "description": "Updated Description",
  "permissions": [
    "sender_admin.security_settings",
    "sender_admin.reports"
    ......
  ]
}

Java SDK

AccountRole accountRole = eslClient.getAccountService().getAccountRole("account_role_id");
accountRole.setDescription("Updated Description");
accountRole.getPermissions().addAll(Arrays.asList("sender_admin.security_settings","sender_admin.reports"));
eslClient.getAccountService().updateAccountRole("account_role_id", accountRole);

Another important use case why you want to use the update call is when you want to cancel an account role. Instead of directly delete the role, you can choose to disable it first. It sets the account role status to disabled which functions the same as delete operation but still keeps the opportunity to recover the cancellation, see below.

REST API

HTTP Request

PUT /api/account/roles/{accountRoleId}

HTTP Headers

Authorization: Basic {your_api_key}
Content-Type: application/json
Accept: application/json

Example Payload

{"enabled":false}

Java SDK

AccountRole accountRole = eslClient.getAccountService().getAccountRole("account_role_id");
accountRole.setEnabled(false);
eslClient.getAccountService().updateAccountRole("account_role_id", accountRole);

If you decided not to keep a disabled account role after testing the adjustment, you can delete the role with:

REST API

HTTP Request

DELETE /api/account/roles/{accountRoleId}

HTTP Headers

Authorization: Basic {your_api_key}

Java SDK

eslClient.getAccountService().deleteAccountRole("account_role_id");

Assign Roles to a Sender

With account roles set up in your account, the next step is to associate the roles to your existing senders. Depending on whether your account has turned on the “Subaccount feature”, use one of the two APIs listed below:

HTTP Request

POST /api/account/senders/{senderId}/roles                                               
POST /api/account/senders/{senderId}/account/{accountId}/roles

HTTP Headers

Authorization: Basic {your_api_key}
Content-Type: application/json
Accept: application/json

Example Payload

[
  {
    "id": "owner"
  },
  {
    "id": "member"
  },
  {
    "id": "manager"
  },
  {
    "id": "dc996466-8a0a-40d2-a9fb-461de2c2fab7"
  }
]

Note:

• If your account hasn’t enabled the Subaccount feature, skip the “/account/{accountId}/” from the API URL. Otherwise, the account ID passed in the URL path should be the subaccount ID where you want this sender to have access to.
• In payload, you will need to provide at least the account role ID for each node.

To retrieve an overview of sender IDs and who is assigned to a given role, use the API or SDK function below:

REST API

HTTP Request

GET /api/account/roles/{accountRoleId}/users

HTTP Headers

Authorization: Basic {your_api_key}
Accept: application/json

Java SDK

List<String> accountRoleUsers = client.getAccountService().getAccountRoleUsers("account_role_id");

We Appreciate Your Feedback

This concludes today’s blog. By now, we have explained how the Roles & Permissions feature get improved compared to its previous implementation, what permissions are available for admin users to define a customized account role, and how developers can integrate this feature into your own application via API and SDK codes.

If you have any questions regarding this blog or anything else concerning the integration of OneSpan Sign into your application, visit the Developer Community Forums. Your feedback matters to us!