Managing API Access and Event Notifications

This section discusses:

API Access
Event Notifications

API Access

For more information on how to use API Tokens, see our blog post on this topic.

To access the API Access page:

Click Admin > API Access.

Customers can communicate with OneSpan Sign from within their own system via REST API calls. The system can authenticate those calls using either of the following techniques:

Client Apps
API Key

Client Apps

Before integrators can make requests via REST APIs or SDK functions, OneSpan Sign requires that users either register a Client Apps, or provide a secure API Key to authenticate the API calls.

To register a Client App

You can authenticate REST API calls from within a user's system by providing the user with a secure but short-lived (e.g., 30-minute) API Token that can be used for authentication. This feature is called Client Apps. To enable it, you must contact our Support Team. Once this feature is enabled, third-party integrators will be able to connect to the OneSpan Sign API using these API Tokens.

This feature is not supported for OneSpan Sign connectors.

To create a Client App

In the Client Apps section of the API Access page, click Add. A Create Client App sidebar appears.
Enter a Name for the Client App.
Click Create.
Copy the Client ID and Secret codes that appear.
Store the Client ID and Secret codes in a secure location.
Click Done.

The Secret will no longer appear once you click Done. For your records. please copy this Secret to a secure location. Both the Client ID and Secret are used to retrieve the temporary API Token.

API Keys

While API keys can be used with OneSpan Sign, we recommend that you use Client Apps instead. Clients Apps are more flexible and help reduce the number of potential security vulnerabilities.

Client apps provide the following benefits over API Keys:

With Client Apps access can be created, rotated, or revoked as needed. API Keys are fixed, and thus if you want to make any access changes you will need to contact our Support Team.
Multiple Client Apps can be used if you have multiple integrations configured. This helps to limit the scope of any fraudulent attack on your system. Conversely, only one API Key is provided for all integrations.
Client Apps use temporary tokens to allow API access, which are only available for a brief period of time. API Keys do not expire, and thus any breach will require you to contact our Support Team.

The API key may not be visible, depending on your environment and your account privileges. Only an account owner can view an API key.

To view your API key

In the API Key section of the API Access page, click the View icon.

By default, your API key is masked.

Data Loss Prevention (DLP)

Client Apps can be configured to work with Data Loss Prevention (DLP) software. If you are using DLP software in your environment, and you would like to configure your software to monitor the Client ID and Client Secret, contact our Support Team.

Event Notifications

To access the Event Notification page:

Click Admin > Event Notification.

OneSpan Sign enables integrators to be automatically notified of events that concern their account. On selected events, the system automatically issues messages to a destination of the integrator's choice. Before OneSpan Sign notifies you of an event, you must register to be notified of it.

To configure Event Notifications on your account:

Click Admin > Event Notification.
Enter a Callback URL. This is a required field.
Optionally, enter a secure Callback Key.
Toggle On the event types for which you want to be notified. By default, notifications for all event types are disabled.
Click Save.

If you've changed your mind, and want to disable all event notifications, click REVERT.

If you would like to enable Event Notification using OAuth Refresh Token Flow you must do so using an API. Note that we currently only support this method on Salesforce.

Account Generated Events

The following events are generated from within an account:

Generated within account	Description
Template created	A new template has been created.
Transaction created	A transaction has been created.
Transaction deleted	A transaction has been permanently deleted from the Trashed folder.
Transaction activated	A transaction has been sent.
Transaction deactivated	The transaction's status changed from SENT to DRAFT.
Transaction ready for completion	A transaction was marked as DO_NOT_AUTOCOMPLETE, and has been signed by all signers. Completion of the transaction requires an action by the sender.
Video recordings ready	After all signers have finished signing a Virtual Room transaction, the recorded session is processed. Once the recordings are ready to download, this notification is sent.
Transaction expired	A transaction has exceeded its expiry date.
Transaction trashed	A transaction was moved to the Trashed folder.
Transaction archived	A transaction has been completed and changed to the Archived status. Archived transactions no longer appear in the user's inbox or dashboard.
Transaction restored	The status of an archived transaction has been changed.

Participant Generated Events

The following events are generated by a participant:

Generated by participants	Description
Email bounce	An email bounce has occurred.
Recipient locked	A recipient has been locked out, due to repeated authentication failures.
KBA failure	There has been a KBA authentication failure.
Role reassigned	A recipient has delegated their signature to another signer.
Transaction attachment added	A recipient uploaded an attachment.
Transaction declined	A recipient has declined to sign the transaction. The notification includes the recipient's reason for declining.
Document viewed	A transaction's document has been viewed.
Co-browse Request	A request for a co-browsing session has been made.
Document signed	A document is signed, and the electronic consent and disclosure agreement has been accepted.
Recipient completed signing	A recipient has completed signing all documents.
Transaction completed	A transaction has been completed by all signers, and the sender has completed the transaction.