Last modified: 2022-01-20

Integration

The Integration section is comprised of the following pages: 

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

  1. In the Client Apps section of the API Access page, click Add. A Create Client App sidebar appears.
  2. Enter a Name for the Client App.
  3. Click Create.
  4. Copy the Client ID and Secret codes that appear.
  5. Store the Client ID and Secret codes in a secure location.
  6. 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.

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

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:

  1. Enter a Callback URL. This is a required field.
  2. Optionally, enter a secure Callback Key.
  3. Toggle On the event types for which you want to be notified. By default, notifications for all event types are disabled.
  4. Click Save.
  5. 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.

Select Events

EventDescription
Transaction createdA transaction has been created.
Transaction expiredA transaction has exceeded its expiry date.
Transaction activatedA transaction has been sent.
Transaction opted out ofA recipient opted out of signing the transaction electronically. The notification includes the recipient's reason for opting out.
Transaction deactivatedThe transaction's status changed from SENT to DRAFT.
Transaction attachmentA recipient uploaded an attachment.
Transaction ready for completionA transaction was marked as DO_NOT_AUTOCOMPLETE, and has been signed by all signers. Completion of the transaction requires an action by the sender.
Document signedA document is signed, and the electronic consent and disclosure agreement has been accepted.
Transaction completedA transaction has been completed by all signers, and the sender has completed the transaction.
Role reassignedA recipient has delegated their signature to another signer.
Transaction trashedA transaction was moved to the Trashed folder.
Recipient completed signingA recipient has completed signing all documents.
Transaction ArchivedA transaction has been completed and changed to the Archived status. Archived transactions no longer appear in the user's inbox or dashboard.
Transaction restoredA transaction in the Trashed folder has been restored to its previous state.
Recipient lockedA recipient has been locked out, due to repeated authentication failures.
Transaction deletedA transaction has been permanently deleted from the Trashed folder.
KBA failureThere has been a KBA authentication failure.
Transaction declinedA recipient has declined to sign the transaction. The notification includes the recipient's reason for declining.
Email bounceAn email bounce has occurred.
Was this information helpful?
X