Managing Roles and Permissions

Java SDK.NET SDKREST API

Java SDK

To download the full code sample see our Code Share site.

With the Roles and Permissions feature, admins have more control over their senders’ access permissions. By creating a customized Account Role with a set of permissions and assigning the role to a sender, it determines the actions available to the sender and makes it easy to manage the access rights of a large number of senders without having to change their respective permissions.

Without turning on the Roles and Permissions feature, admins are only able to specify two static role types: “Sender” and “Manager”. This may be insufficient when the number of senders grows and they need access to different elements in the account. Assigning roles and permissions to your senders allows you to control this.

Turn on roles and permissions

By default, the Roles and Permissions feature is disabled, so admins should contact our Support Team to arrange this configuration in the account. Once enabled, the option to configure Roles will appear in the OneSpan Sign Admin menu. For more information, see Managing Roles.

When making API calls with an API Key, OneSpan Sign creates an API Key session if one is not already in use. If an API Key session has already been created, then OneSpan Sign will use the existing session. However, if Roles and Permissions have been cached in this session then any changes that are made will not appear until the session expires. By default, API Key sessions expire after 15 minutes.

Available permissions

With a role-based access model, you can group senders with similar needs into a role. You then grant permissions to the role which determine the pages and actions the senders can access. The following table describes all of the permissions in OneSpan Sign. Note that each permission has a Permission ID which you will use when setting up the roles and permissions for your organization.

If a specific feature is not enabled for an account then the permission associated to that feature is not available. Also, the available permissions may change when new features and releases are rolled out to an account.

When creating custom roles via integration, you must ensure to include the template permission as well and not depend on the existing "Transaction" permission to determine whether templates are allowed to be created/updated/deleted.

Manage account roles

By default, OneSpan Sign offers the following roles, each with their own default permission sets:

• Administrator: Has full access to the application and its configurations

• Manager: Has full access to the application

  If Enterprise Administration has been enabled for your account a Manager will not be able to assign a delegate for any of their senders.

• Sender: Has limited access to the application

• Notary: Has limited access to the application, with additional notary functions.

• These default roles are not customizable, and they cannot be deleted. Account Administrators can nonetheless: (1) create customized roles, assigning a customized set of permissions to each one; (2) make a customized role available within specified accounts.

Should you need to create additional custom roles you can do so using the Java SDK.

Ensure your SDK is version 11.35 or higher.

To create an account role:

AccountRole accountRole = AccountRoleBuilder.newAccountRole()
	.withName("Regional Manager")
	.withPermissions(Arrays.asList("transaction.transaction", "transaction.in_person"))
	.withDescription("Customized Role for Regional Manager")
	.withEnabled(true)
	.build();
eslClient.getAccountService().addAccountRole(accountRole);

As a response, an account role ID formatted in UUID will be returned. Store this ID to a local file because you will need to reference it for additional procedures.

To query a specific account role by its ID:

AccountRole accountRole = eslClient.getAccountService().getAccountRole("account_role_id");

To retrieve a list of all the existing account roles:

List<AccountRole> accountRoles = eslClient.getAccountService().getAccountRoles();

To update an account role name, description or associated permissions:

A user cannot update their own role.

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);

To disable an account role:

Instead of directly deleting a role, you can choose to disable it first. Disabling the account role functions the same as the delete operation but leaves you with the option to enable the role again, if needed.

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

To delete an account role:

If you decide not to keep a disabled account role, you can delete the role.

This action is not reversible.

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

To retrieve a list of sender IDs assigned to a role:

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

Results

Here is an example of what you can expect to see once you have run your code.

After executing the sample code, you can find your newly-created account roles in your OneSpan Sign account. Navigate to Admin > Roles to see the original and custom account roles.

Assign an account role to a sender

With the account roles set up in your account, the next step is to associate the roles to your existing sender.

To assign an account role to a sender:

List<AccountRole> acountRoles = new ArrayList<>();
acountRoles.add(AccountRoleBuilder.newAccountRole().withId("your_account_role_id1").build());
acountRoles.add(AccountRoleBuilder.newAccountRole().withId("your_account_role_id2").build());
acountRoles.add(AccountRoleBuilder.newAccountRole().withId("your_account_role_id3").build());
UserAccountRole userAccountRole = new UserAccountRole("sender_id","accountId",acountRoles);
userAccountRole = client.getAccountService().assignAccountRoleToUser(userAccountRole.getUserId(),
userAccountRole);

.NET SDK

To download the full code sample see our Code Share site.

With the Roles and Permissions feature, admins have more control over their senders’ access permissions. By creating a customized Account Role with a set of permissions and assigning the role to a sender, it determines the actions available to the sender and makes it easy to manage the access rights of a large number of senders without having to change their respective permissions.

Without turning on the Roles and Permissions feature, admins are only able to specify two static role types: “Sender” and “Manager”. This may be insufficient when the number of senders grows and they need access to different elements in the account. Assigning roles and permissions to your senders allows you to control this.

Turn on roles and permissions

By default, the Roles and Permissions feature is disabled, so admins should contact our Support Team to arrange this configuration in the account. Once enabled, the option to configure Roles will appear in the OneSpan Sign Admin menu. For more information, see Managing Roles.

When making API calls with an API Key, OneSpan Sign creates an API Key session if one is not already in use. If an API Key session has already been created, then OneSpan Sign will use the existing session. However, if Roles and Permissions have been cached in this session then any changes that are made will not appear until the session expires. By default, API Key sessions expire after 15 minutes.

Available permissions

With a role-based access model, you can group senders with similar needs into a role. You then grant permissions to the role which determine the pages and actions the senders can access. The following table describes all of the permissions in OneSpan Sign. Note that each permission has a Permission ID which you will use when setting up the roles and permissions for your organization.

If a specific feature is not enabled for an account then the permission associated to that feature is not available. Also, the available permissions may change when new features and releases are rolled out to an account.

When creating custom roles via integration, you must ensure to include the template permission as well and not depend on the existing "Transaction" permission to determine whether templates are allowed to be created/updated/deleted.

Manage account roles

By default, OneSpan Sign offers the following roles, each with their own default permission sets:

• Administrator: Has full access to the application and its configurations

• Manager: Has full access to the application

  If Enterprise Administration has been enabled for your account a Manager will not be able to assign a delegate for any of their senders.

• Sender: Has limited access to the application

• Notary: Has limited access to the application, with additional notary functions.

• These default roles are not customizable, and they cannot be deleted. Account Administrators can nonetheless: (1) create customized roles, assigning a customized set of permissions to each one; (2) make a customized role available within specified accounts.

Should you need to create additional custom roles you can do so using the Java SDK.

Ensure your SDK is version 11.35 or higher.

To create an account role:

	
				//create
				AccountRole accountRole = AccountRoleBuilder.NewAccountRole()
				.WithName("Sales Manager")
				.WithPermissions(new List<String> { "transaction.transaction", "transaction.in_person" })
					.WithDescription("Customized Role for Regional Manager")
					.WithEnabled(true)
					.Build();
					ossClient.AccountService.addAccountRole(accountRole);
					//			
				

As a response, an account role ID formatted in UUID will be returned. Store this ID to a local file because you will need to reference it for additional procedures.

To query a specific account role by its ID:

AccountRole accountRole1 = ossClient.AccountService.getAccountRole("account_role_id");	

To retrieve a list of all the existing account roles:

List<AccountRole> accountRoles = ossClient.AccountService.getAccountRoles();

To update an account role name, description or associated permissions:

 AccountRole accountRole2 = ossClient.AccountService.getAccountRole("account_role_id");
				accountRole2.Description = "Updated Description";
				accountRole2.Permissions.AddRange(new List<String> { "sender_admin.security_settings", "sender_admin.reports" });
			ossClient.AccountService.updateAccountRole("account_role_id", accountRole2);

To disable an account role:

Instead of directly deleting a role, you can choose to disable it first. Disabling the account role functions the same as the delete operation but leaves you with the option to enable the role again, if needed.

AccountRole accountRole3 = ossClient.AccountService.getAccountRole("account_role_id");
				accountRole3.Enabled = false;
			ossClient.AccountService.updateAccountRole("account_role_id", accountRole3);

To delete an account role:

If you decide not to keep a disabled account role, you can delete the role.

This action is not reversible.

ossClient.AccountService.deleteAccountRole("account_role_id");

To retrieve a list of sender IDs assigned to a role:

List<String> accountRoleUsers = ossClient.AccountService.getAccountRoleUsers("account_role_id");
			Collap

Results

Here is an example of what you can expect to see once you have run your code.

After executing the sample code, you can find your newly-created account roles in your OneSpan Sign account. Navigate to Admin > Roles to see the original and custom account roles.

Assign an account role to a sender

With the account roles set up in your account, the next step is to associate the roles to your existing sender.

To assign an account role to a sender:

List<AccountRole> acountRoles = new ArrayList<>();
acountRoles.add(AccountRoleBuilder.newAccountRole().withId("your_account_role_id1").build());
acountRoles.add(AccountRoleBuilder.newAccountRole().withId("your_account_role_id2").build());
acountRoles.add(AccountRoleBuilder.newAccountRole().withId("your_account_role_id3").build());
UserAccountRole userAccountRole = new UserAccountRole("sender_id","accountId",acountRoles);
userAccountRole = client.getAccountService().assignAccountRoleToUser(userAccountRole.getUserId(),
userAccountRole);

REST API

To download the full code sample see our Code Share site.

With the Roles and Permissions feature, admins have more control over their senders’ access permissions. By creating a customized Account Role with a set of permissions and assigning the role to a sender, it determines the actions available to the sender and makes it easy to manage the access rights of a large number of senders without having to change their respective permissions.

Without turning on the Roles and Permissions feature, admins are only able to specify two static role types: “Sender” and “Manager”. This may be insufficient when the number of senders grows and they need access to different elements in the account. Assigning roles and permissions to your senders allows you to control this.

Turn on roles and permissions

By default, the Roles and Permissions feature is disabled, so admins should contact our Support Team to arrange this configuration in the account. Once enabled, the option to configure Roles will appear in the OneSpan Sign Admin menu. For more information, see Managing Roles.

When making API calls with an API Key, OneSpan Sign creates an API Key session if one is not already in use. If an API Key session has already been created, then OneSpan Sign will use the existing session. However, if Roles and Permissions have been cached in this session then any changes that are made will not appear until the session expires. By default, API Key sessions expire after 15 minutes.

Available permissions

With a role-based access model, you can group senders with similar needs into a role. You then grant permissions to the role which determine the pages and actions the senders can access. The following table describes all of the permissions in OneSpan Sign. Note that each permission has a Permission ID which you will use when setting up the roles and permissions for your organization.

If a specific feature is not enabled for an account then the permission associated to that feature is not available. Also, the available permissions may change when new features and releases are rolled out to an account.

When creating custom roles via integration, you must ensure to include the template permission as well and not depend on the existing "Transaction" permission to determine whether templates are allowed to be created/updated/deleted.

Manage account roles

By default, OneSpan Sign offers the following roles, each with their own default permission sets:

• Administrator: Has full access to the application and its configurations

• Manager: Has full access to the application

  If Enterprise Administration has been enabled for your account a Manager will not be able to assign a delegate for any of their senders.

• Sender: Has limited access to the application

• Notary: Has limited access to the application, with additional notary functions.

• These default roles are not customizable, and they cannot be deleted. Account Administrators can nonetheless: (1) create customized roles, assigning a customized set of permissions to each one; (2) make a customized role available within specified accounts.

Should you need to create additional custom roles, you can do so using the RESTful API.

To create an account role:

HTTP Request

POST /api/account/roles

HTTP Headers

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

Example Payload

 {
	"name": "Regional Manager", 
	"enabled": true, 
	"description": "Customized Role for Regional Manager",
	"permissions": 
		["transaction.transaction",
		 "transaction.in_person",
		  ......]
 }

As a response, an account role ID formatted in UUID will be returned. Store this ID to a local file because you will need to reference it for additional procedures.

To query a specific account role by its ID, or to retrieve a list of all the existing account roles:

HTTP Request

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

HTTP Headers

Authorization: Basic {your_api_key}			
Accept: application/json 

To update an account role name, description or associated permissions:

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"
	 	 ...... ]
 }

To disable an account role:

Instead of directly deleting a role, you can choose to disable it first. Disabling the account role functions the same as the delete operation but leaves you with the option to enable the role again, if needed.

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} 

To delete an account role:

If you decide not to keep a disabled account role, you can delete the role.

This action is not reversible.

HTTP Request

DELETE /api/account/roles/{accountRoleId} 

HTTP Headers

Authorization: Basic {your_api_key} 
Assign Role to Sender 

Assign an account role to a sender

With the account roles set up in your account, the next step is to associate the roles to your existing sender with this API.

To assign an account role to a sender:

HTTP Request

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

HTTP Headers

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

Example Payload

 {
	"accountId" : "Us1VqQw3r3kN",
	"accountRoles": [ {"id": "owner"}, {"id": "member"}]
 }

• For an "accountRoles" array, you must provide the account role ID for each node.

To retrieve a list of sender IDs assigned to a role:

HTTP Request

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

HTTP Headers

Authorization: Basic {your_api_key} 
Accept: application/json 

Results

Here is an example of what you can expect to see once you have run your code.

After executing the sample code, you can find your newly-created account roles in your OneSpan Sign account. Navigate to Admin > Roles to see the original and custom account roles.

You can confirm the sender is associated with the account role by navigating to Admin > Users to locate the sender's profile.