Delegating Access

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

The Access Delegation option enables a user to delegate access to their OneSpan Sign transactions to one or more other users on their account. Specifically, delegates can sign documents on behalf of the delegator, and they can access the delegator's inbox, drafts, layouts, and templates. All transactions performed by the delegate nonetheless continue to be owned by the delegator.

This feature addresses use cases like the following:

• A manager must manage transactions, monitor transaction progress, and retrieve completed documents for employees who have sent transaction emails, but who are unavailable at the moment (perhaps they're on vacation, or they've left the company).

• A group of users is responsible for distributing transactions. While one member of the group is away, another member must access the absent member's OneSpan Sign folders to: (1) see if a transaction was sent or completed; (2) retrieve any completed documents.

Retrieving Users

The first step to delegating access is to retrieve a list of users from your OneSpan Sign account, which is described in the following code example. Included in this list are your user's email addresses, and their IDs. User IDs are required to add and remove delegates.

The maximum number of users that you can retrieve, as defined by this API, is 100.

Here is some sample code that describes how to do this. In this example, the number of users returned in the list is 5, as defined by PageRequest.

int i = 1;
Map<String, Sender> accountMembers = client.getAccountService().getSenders(Direction.ASCENDING, new PageRequest(i,5));
		
while(!accountMembers.isEmpty()) {
for (Map.Entry entry : accountMembers.entrySet()) {
		String email = (String) entry.getKey();
		Sender sender = (Sender) entry.getValue();
		System.out.println(email + ", " + sender.getId());
		i++;
				}
accountMembers =  client.getAccountService().getSenders(Direction.ASCENDING, new PageRequest(i,5));
}

Adding Delegates

To add delegates you need to define which sender will be allowing delegates. This is done using your OneSpan Sign AccountService. To define a specific sender you need their Sender ID, which you obtained in the previous step. Once you have your Sender ID, you can then build your DelegationUser object and call your OneSpan Sign client AccountService to add a delegate.

To add delegates you also need your user ID, which is also retrieved using the code above.

Here is some sample code that describes how to do this.

Sender user1 =  client.getAccountService().getSender(sender1Id);
DelegationUser delegationUser1 = DelegationUserBuilder.newDelegationUser(user1).build();
client.getAccountService().addDelegate(ownerId, delegationUser1);

Removing Delegates

To remove a delegate, simply call on your OneSpan Sign client AccountService. Similar to adding delegates, you will need your user and Sender IDs.

Here is some sample code that describes how to do this.

client.getAccountService().removeDelegate(ownerId, sender1Id);

Bulk Updating

You can also do a bulk update of your delegates list. To do this, create a list of delegate IDs and use the AccountService to update your delegates.

Performing a bulk update will clear all of your current delegates and replace them with the ones defined in your list. Make sure that you list ALL of the delegates that you want to give access to, including those that were already granted access.

Here is some sample code that describes how to do this.

List<String> delegateIds = new ArrayList<String>();
delegateIds.add(sender1Id);
delegateIds.add(sender2Id);
delegateIds.add(sender3Id);
        
client.getAccountService().updateDelegates(ownerId, delegateIds);

Finding Existing Delegates

To create a list of existing delegates, use the following AccountService call.

List<DelegationUser> delegates = client.getAccountService().getDelegates(ownerId);
int  i = 1;
for(DelegationUser delegate : delegates) {
      System.out.println("Delegate " + i + ": " + delegate.getName() + ", with email " + delegate.getEmail());
      i++;
}

Clearing Delegates

To clear all of your delegates, use the following command. Again, you will need your user ID.

client.getAccountService().clearDelegates(ownerId);

Results

Here is an example of the list created when you retrieved a list of sender emails and IDs.

Here is an example of a retrieved list of delegates, which includes their full and name and email addresses.

On the Access Delegation page, you will find a list of users that can manage your transactions using your OneSpan Sign account.

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

The Access Delegation option enables a user to delegate access to their OneSpan Sign transactions to one or more other users on their account. Specifically, delegates can sign documents on behalf of the delegator, and they can access the delegator's inbox, drafts, layouts, and templates. All transactions performed by the delegate nonetheless continue to be owned by the delegator.

This feature addresses use cases like the following:

• A manager must manage transactions, monitor transaction progress, and retrieve completed documents for employees who have sent transaction emails, but who are unavailable at the moment (perhaps they're on vacation, or they've left the company).

• A group of users is responsible for distributing transactions. While one member of the group is away, another member must access the absent member's OneSpan Sign folders to: (1) see if a transaction was sent or completed; (2) retrieve any completed documents.

int i = 1;
IDictionary<string, Sender> accountMembers = client.AccountService.GetSenders(Direction.ASCENDING, new PageRequest(i, 5));
        while (accountMembers.Count != 0)
        {
            foreach (var s in accountMembers)
            {
                string email = s.Key.ToString();
                string id = s.Value.Id;
                Debug.WriteLine(email + " " + id);
                i++;
            }
            accountMembers = client.AccountService.GetSenders(Direction.ASCENDING, new PageRequest(i, 5));
        }

Adding Delegates

To add delegates you need to define which sender will be allowing delegates. This is done using your OneSpan Sign AccountService. To define a specific sender you need their Sender ID, which you obtained in the previous step. Once you have your Sender ID, you can then build your DelegationUser object and call your OneSpan Sign client AccountService to add a delegate.

To add delegates you also need your user ID, which is also retrieved using the code above.

Here is some sample code that describes how to do this.

Sender user1 = client.AccountService.GetSender(sender1Id);
DelegationUser delegationUser1 = DelegationUserBuilder.NewDelegationUser(user1).Build();
client.AccountService.AddDelegate(ownerId, delegationUser1);

Removing Delegates

To remove a delegate, simply call on your OneSpan Sign client AccountService. Similar to adding delegates, you will need your user and Sender IDs.

Here is some sample code that describes how to do this.

client.AccountService.RemoveDelegate(ownerId, sender1Id);

Bulk Updating

You can also do a bulk update of your delegates list. To do this, create a list of delegate IDs and use the AccountService to update your delegates.

Performing a bulk update will clear all of your current delegates and replace them with the ones defined in your list. Make sure that you list ALL of the delegates that you want to give access to, including those that were already granted access.

Here is some sample code that describes how to do this.

List<string> delegateIds = new List<string>();
delegateIds.Add(sender1Id);
delegateIds.Add(sender2Id);
delegateIds.Add(sender3Id);
client.AccountService.UpdateDelegates(ownerId, delegateIds);

Finding Existing Delegates

To create a list of existing delegates, use the following AccountService call.

IList<DelegationUser> delegates = client.AccountService.GetDelegates(ownerId);
int i = 1;
foreach (var user in delegates){
     Debug.WriteLine("Delegate " + i + ": " + user.Name + " with email " + user.Email);
     i++;
}

Clearing Delegates

To clear all of your delegates, use the following command. Again, you will need your user ID.

client.AccountService.ClearDelegates(ownerId);

Results

Here is an example of the list created when you retrieved a list of sender emails and IDs.

Here is an example of a retrieved list of delegates, which includes their full and name and email addresses.

On the Access Delegation page, you will find a list of users that can manage your transactions using your OneSpan Sign account.

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

The Access Delegation option enables a user to delegate access to their OneSpan Sign transactions to one or more other users on their account. Specifically, delegates can sign documents on behalf of the delegator, and they can access the delegator's inbox, drafts, layouts, and templates. All transactions performed by the delegate nonetheless continue to be owned by the delegator.

This feature addresses use cases like the following:

• A manager must manage transactions, monitor transaction progress, and retrieve completed documents for employees who have sent transaction emails, but who are unavailable at the moment (perhaps they're on vacation, or they've left the company).

• A group of users is responsible for distributing transactions. While one member of the group is away, another member must access the absent member's OneSpan Sign folders to: (1) see if a transaction was sent or completed; (2) retrieve any completed documents.

Retrieving Senders

The first step to delegating access is to retrieve a list of senders from your OneSpan Sign account. To do so, use the commands in the following sections.

HTTP Request

GET /api/account/senders?from=0&to=100

HTTP Headers

Accept: application/json
Content-Type: application/json
Authorization: Basic api_key

Response Payload

The Request Payload provides a description of each field.

{
  "results": [
    {
      "status": "ACTIVE",
      "language": "en",
      "signature": null,
      "id": "IBCyHvarzWsX",
      "data": {
        "hasNotCreatedATransaction": true,
        "showIntro": true
      },
      "account": {
        "id": "3vD0Dc9Fh7wQ",
        "data": null,
        "updated": "2016-05-05T19:30:13Z",
        "company": {
          "id": "jVWmyg4cyis8",
          "data": null,
          "address": {
            "address1": null,
            "address2": null,
            "city": null,
            "country": null,
            "zipcode": null,
            "state": null
          },
          "name": "OneSpan Sign"
        },
        "licenses": [
          {
            "status": "ACTIVE",
            "paidUntil": "2020-05-05T00:00:00Z",
            "plan": {
              "group": "",
              "description": "E-Sign Hundreds of Documents with Unlimited Signers",
              "id": "sandbox",
              "features": null,
              "price": {
                "amount": 0,
                "currency": {
                  "id": "USD",
                  "data": null,
                  "name": "US Dollar"
                }
              },
              "original": null,
              "cycle": "YEAR",
              "contract": "YEAR",
              "freeCycles": null,
              "quotas": [
                {
                  "cycle": null,
                  "scope": "ACCOUNT",
                  "limit": 100,
                  "target": "SENDER"
                },
                {
                  "cycle": null,
                  "scope": "SENDER",
                  "limit": 500,
                  "target": "DOCUMENT"
                },
                {
                  "cycle": null,
                  "scope": "SENDER",
                  "limit": 500,
                  "target": "STORAGE"
                }
              ],
              "data": null,
              "name": "Sandbox"
            },
            "transactions": [],
            "created": "2016-05-05T19:30:13Z"
          }
        ],
        "logoUrl": "",
        "providers": null,
        "customFields": [
          {
            "required": false,
            "id": "policy_number_id",
            "data": null,
            "translations": [
              {
                "description": "Car Insurance Policy Number.",
                "language": "en",
                "id": "",
                "data": null,
                "name": "Policy Number"
              }
            ],
            "value": "123-456-789-0",
            "name": ""
          }
        ],
        "created": "2016-05-05T19:30:13Z",
        "owner": "ZQI8k6faVoM8",
        "name": "Haris Haidary"
      },
      "title": null,
      "external": null,
      "updated": "2017-11-13T15:07:49Z",
      "memberships": [],
      "phone": "",
      "professionalIdentityFields": [],
      "userCustomFields": [],
      "locked": null,
      "activated": null,
      "company": "",
      "email": "mail73@example.com",
      "firstName": "John",
      "lastName": "Smith",
      "type": "REGULAR",
      "name": "",
      "address": null,
      "created": "2017-11-13T15:07:49Z",
      "specialTypes": [],
      "hasDelegates": false
    }
  ],
  "count": 1
}

Adding Delegates

To add a delegate, you will need to retrieve your sender IDs, which you can get from the call above. To add a delegate, you will need to make the following request:

HTTP Request

PUT /api/account/senders/{senderId}/delegates

HTTP Headers

Accept: application/json
Content-Type: application/json
Authorization: Basic api_key

Request Payload

["delegateSenderId"]

Removing Delegates

Similar to adding delegates, you will need your sender ID to remove a delegate. To do so, make the following request:

HTTP Request

DELETE /api/account/senders/{senderId}/delegates

HTTP Headers

Accept: application/json
Content-Type: application/json
Authorization: Basic api_key

Request Payload

["delegateSenderId"]

Bulk Updating

You can also do a bulk update of your delegates list.

Performing a bulk update will clear all of your current delegates and replace them with the ones defined in your list.

HTTP Request

PUT /api/account/senders/{senderId}/delegates

HTTP Headers

Accept: application/json
Content-Type: application/json
Authorization: Basic api_key

Finding Existing Delegates

If you would like to know who is already a delegate on your account, use the following command:

["delegateSenderId1","delegateSenderId2", "delegateSenderId3"]

HTTP Request

GET /api/account/senders/{senderId}/delegates

HTTP Headers

Accept: application/json
Content-Type: application/json
Authorization: Basic api_key

Response Payload

[
  {
    "email": "mary.doe@example.com",
    "firstName": "Mary",
    "lastName": "Doe",
    "id": "bYDFWxGOYmAV",
    "data": null,
    "name": "Mary Doe"
  },
  {
    "email": "john.smith@example.com",
    "firstName": "John",
    "lastName": "Smith",
    "id": "T3AY60Ev33o0",
    "data": null,
    "name": "John Smith"
  }
]

Results

On the Access Delegation page, you will find a list of users that can manage your transactions using your OneSpan Sign account.