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!
