Last modified: 2024-03-04

Managing API Access and Event Notification

This section discusses:

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

  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. 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 Notification

To access the Event Notification page:

  • Click Admin > 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. Click Admin > Event Notifications.
  2. Enter a Callback URL. This is a required field.
  3. Select your Authentication Method. Depending on the method selected different configurations can be set:
    1. None: Only a Callback URL is required.
    2. Basic: Enter a secure Callback Key.
    3. OAuth2.0: If OAuth 2.0 is select, then additional configurations are required:
      • Client ID: This is configured in your authorization server for the application.
      • Client Secret: This is configured in your authorization server for the application.
      • Authorization Server URL: The URL of your authorization server for the application.
      • Scope: Used to limit access to an account, configured in the authorization server for the application. This information should be provided by the user.
  4. Optionally, toggle on the event types, Account or Participant generated, for which you want to be notified. By default, notifications for all event types are disabled.
  5. 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 accountDescription
Template createdA new template has been created.
Transaction createdA transaction has been created.
Transaction deletedA transaction has been permanently deleted from the Trashed folder.
Transaction activatedA transaction has been sent.
Transaction deactivatedThe transaction's status changed from SENT to DRAFT.
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.
Video recordings readyAfter 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 expiredA transaction has exceeded its expiry date.
Transaction trashedA transaction was moved to the Trashed folder.
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 restoredThe status of an archived transaction has been changed.

Participant Generated Events

The following events are generated by a participant:

Generated by participantsDescription
Email bounceAn email bounce has occurred.
Recipient lockedA recipient has been locked out, due to repeated authentication failures.
KBA failureThere has been a KBA authentication failure.
Role reassignedA recipient has delegated their signature to another signer.
Transaction attachment addedA recipient uploaded an attachment.
Transaction declinedA recipient has declined to sign the transaction. The notification includes the recipient's reason for declining.
Document viewedA transaction's document has been viewed.
Co-browse RequestA request for a co-browsing session has been made.
Document signedA document is signed, and the electronic consent and disclosure agreement has been accepted.
Recipient completed signingA recipient has completed signing all documents.
Transaction completedA transaction has been completed by all signers, and the sender has completed the transaction.
Was this information helpful?