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.

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.

Permission Permission ID Description
OneSpan Trust Vault (Compliance Vault) Permissions
No access   This permission denies access to the OneSpan Trust Vault (Compliance Vault).
View their own transactions   This permission enables a Sender to view any of their transactions that have been archived to the OneSpan Trust Vault (Compliance Vault).
View and delete their own transactions   This permission enables a Sender to view and delete any of their transactions that have been archived to the OneSpan Trust Vault (Compliance Vault).
View all transactions   This permission enables a Sender to view all transactions that have been archived to the OneSpan Trust Vault (Compliance Vault).
View and delete all transactions   This permission enables a Sender to view and delete all transactions that have been archived to the OneSpan Trust Vault (Compliance Vault).
Sender Admin Permissions
Custom Fields sender_admin.custom_fields This permission enables a Sender to create and manage Custom Fields.
User Management sender_admin.users This permission enables a Sender to manage the users associated with their account.
Subscription account billing details sender_admin.subscription

This permission enables a Sender to view the Subscription page, which contains billing details for their account.

API Access sender_admin.api_access This permission enables a Sender to allow customers to communicate with OneSpan Sign from within their own system via REST API calls.
Event Notification sender_admin.event_notification This permission enables a Sender to view their account's Event Notifications interface. Integrators can use this interface to request an automatic notification of events that concern the account.
Data Management sender_admin.data_management

This permission enables a Sender to specify how long transactions in various states will be retained on a OneSpan Sign server.

Signing Customization sender_admin.customization

This permission enables a Sender to re-brand the Signer Experience in several powerful ways.

Notary sender_admin.notary

This permission enables a Sender to enable the e-Notary feature on a notary’s account. This feature enables the notary to e-sign and notarize documents in a “notarized transaction”.

Security Settings sender_admin.security_settings

This permission enables a Sender to specify a password policy for their account.

Account Configuration sender_admin.self_serve_account_settings This permission enables a sender to access the Account Configuration page.
Reports sender_admin.reports This permission enables a Sender to view the Reports menu in the Navigation Bar, and thus access reports about their account.
Roles sender_admin.role This permission enables a Sender to manage the roles associated with their account.
Group Permissions
Group Signing Management groups.group_signing_management This permission enables an Account Owner or Manager to manage Groups on their account (Sender UI Email Groups).
Template and Layout Permissions
Share Template templates_layouts.share_templates This permission enables a Sender to make their templates available to other users on their account.
Share Layout templates_layouts.share_layouts This permission enables a Sender to make their layouts available to other users on their account.
Transaction Permissions
Transaction transaction.transaction This permission enables a signer to create, view and edit transactions.
In Person Signing transaction.in_person This permission enables a Sender to use the In-Person signing feature on a transaction.
Change Signer Option transaction.change_signer This permission enables a signer to delegate their signing responsibilities to another person.
Transaction visibility in delegation transaction.delegation_visibility

This permission enables a delegate to see all the transactions on the account they have been delegated to manage.

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

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.

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.

Permission Permission ID Description
OneSpan Trust Vault (Compliance Vault) Permissions
No access   This permission denies access to the OneSpan Trust Vault (Compliance Vault).
View their own transactions   This permission enables a Sender to view any of their transactions that have been archived to the OneSpan Trust Vault (Compliance Vault).
View and delete their own transactions   This permission enables a Sender to view and delete any of their transactions that have been archived to the OneSpan Trust Vault (Compliance Vault).
View all transactions   This permission enables a Sender to view all transactions that have been archived to the OneSpan Trust Vault (Compliance Vault).
View and delete all transactions   This permission enables a Sender to view and delete all transactions that have been archived to the OneSpan Trust Vault (Compliance Vault).
Sender Admin Permissions
Custom Fields sender_admin.custom_fields This permission enables a Sender to create and manage Custom Fields.
User Management sender_admin.users This permission enables a Sender to manage the users associated with their account.
Subscription account billing details sender_admin.subscription

This permission enables a Sender to view the Subscription page, which contains billing details for their account.

API Access sender_admin.api_access This permission enables a Sender to allow customers to communicate with OneSpan Sign from within their own system via REST API calls.
Event Notification sender_admin.event_notification This permission enables a Sender to view their account's Event Notifications interface. Integrators can use this interface to request an automatic notification of events that concern the account.
Data Management sender_admin.data_management

This permission enables a Sender to specify how long transactions in various states will be retained on a OneSpan Sign server.

Signing Customization sender_admin.customization

This permission enables a Sender to re-brand the Signer Experience in several powerful ways.

Notary sender_admin.notary

This permission enables a Sender to enable the e-Notary feature on a notary’s account. This feature enables the notary to e-sign and notarize documents in a “notarized transaction”.

Security Settings sender_admin.security_settings

This permission enables a Sender to specify a password policy for their account.

Account Configuration sender_admin.self_serve_account_settings This permission enables a sender to access the Account Configuration page.
Reports sender_admin.reports This permission enables a Sender to view the Reports menu in the Navigation Bar, and thus access reports about their account.
Roles sender_admin.role This permission enables a Sender to manage the roles associated with their account.
Group Permissions
Group Signing Management groups.group_signing_management This permission enables an Account Owner or Manager to manage Groups on their account (Sender UI Email Groups).
Template and Layout Permissions
Share Template templates_layouts.share_templates This permission enables a Sender to make their templates available to other users on their account.
Share Layout templates_layouts.share_layouts This permission enables a Sender to make their layouts available to other users on their account.
Transaction Permissions
Transaction transaction.transaction This permission enables a signer to create, view and edit transactions.
In Person Signing transaction.in_person This permission enables a Sender to use the In-Person signing feature on a transaction.
Change Signer Option transaction.change_signer This permission enables a signer to delegate their signing responsibilities to another person.
Transaction visibility in delegation transaction.delegation_visibility

This permission enables a delegate to see all the transactions on the account they have been delegated to manage.

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

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.

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.

Permission Permission ID Description
OneSpan Trust Vault (Compliance Vault) Permissions
No access   This permission denies access to the OneSpan Trust Vault (Compliance Vault).
View their own transactions   This permission enables a Sender to view any of their transactions that have been archived to the OneSpan Trust Vault (Compliance Vault).
View and delete their own transactions   This permission enables a Sender to view and delete any of their transactions that have been archived to the OneSpan Trust Vault (Compliance Vault).
View all transactions   This permission enables a Sender to view all transactions that have been archived to the OneSpan Trust Vault (Compliance Vault).
View and delete all transactions   This permission enables a Sender to view and delete all transactions that have been archived to the OneSpan Trust Vault (Compliance Vault).
Sender Admin Permissions
Custom Fields sender_admin.custom_fields This permission enables a Sender to create and manage Custom Fields.
User Management sender_admin.users This permission enables a Sender to manage the users associated with their account.
Subscription account billing details sender_admin.subscription

This permission enables a Sender to view the Subscription page, which contains billing details for their account.

API Access sender_admin.api_access This permission enables a Sender to allow customers to communicate with OneSpan Sign from within their own system via REST API calls.
Event Notification sender_admin.event_notification This permission enables a Sender to view their account's Event Notifications interface. Integrators can use this interface to request an automatic notification of events that concern the account.
Data Management sender_admin.data_management

This permission enables a Sender to specify how long transactions in various states will be retained on a OneSpan Sign server.

Signing Customization sender_admin.customization

This permission enables a Sender to re-brand the Signer Experience in several powerful ways.

Notary sender_admin.notary

This permission enables a Sender to enable the e-Notary feature on a notary’s account. This feature enables the notary to e-sign and notarize documents in a “notarized transaction”.

Security Settings sender_admin.security_settings

This permission enables a Sender to specify a password policy for their account.

Account Configuration sender_admin.self_serve_account_settings This permission enables a sender to access the Account Configuration page.
Reports sender_admin.reports This permission enables a Sender to view the Reports menu in the Navigation Bar, and thus access reports about their account.
Roles sender_admin.role This permission enables a Sender to manage the roles associated with their account.
Group Permissions
Group Signing Management groups.group_signing_management This permission enables an Account Owner or Manager to manage Groups on their account (Sender UI Email Groups).
Template and Layout Permissions
Share Template templates_layouts.share_templates This permission enables a Sender to make their templates available to other users on their account.
Share Layout templates_layouts.share_layouts This permission enables a Sender to make their layouts available to other users on their account.
Transaction Permissions
Transaction transaction.transaction This permission enables a signer to create, view and edit transactions.
In Person Signing transaction.in_person This permission enables a Sender to use the In-Person signing feature on a transaction.
Change Signer Option transaction.change_signer This permission enables a signer to delegate their signing responsibilities to another person.
Transaction visibility in delegation transaction.delegation_visibility

This permission enables a delegate to see all the transactions on the account they have been delegated to manage.

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.