Header | Description | Example Value |
---|
apiToken | The user specific API token | e.g. "asdfngtmvv8pfmsuaxpzz85zux3e63dd9zttrwitx9mln6qka6tds83du3p3lroe" |
Such an organization key can be created in Settings→API Tokens and Apps; Section "API Tokens".
Tokens created by eSAW are currently 66-digit alphanumeric strings - but the length and set of allowed characters may be changed with future product versions.
The User Key can also be retrieved, for integration scenarios, by implementing an OAuth Authorization Code Flow.
Bearer token Authorization
Currently avaiable for just some API methods (e.g. sspfile/uploadtemporary).
The same key as used for the userKey header authorization can be used as bearer token.
OrganizationKey and UserLogin Header
You can set the userlogin name and an organization-wide organization key in the HTTP headers. We recommend to avoid using organization key authorization in scenarios where the organization key has to be shared with users, as it may be misused to gain access to other sender's envelopes. Note that the key can be any 32digit alphanum value; not necessarily following the GUID format! The length and set of allowed characters may be changed with future product versions.
Header | Description | Example Value |
---|
OrganizationKey | The organization wide token | e.g. "1234abcd-1a2b-fedc-01a3-9876ba12cdef" or "abxdz1m8a805lhq4awnfkx8jsbrlqsup" |
UserLoginName | The user name (=email address) of the user who has access to the data (e.g.: sender of an envelope) | john.doe@example.com |
Such an organization key can be created in Settings→API Tokens and Apps; Section "Organization API Tokens". Note that it is necessary to activate Organizationkey feature flag to get the option to create an organization key, if the instance was set up with a newer product version; otherwise the section will not be visible.
Callbacks
The API allows the definition of several callbacks. Please note, that only the envelope callback (directly from eSignAnyWhere) is fired, when the envelope is in a final state. The status update callback is fired by a sub-component and you may require to wait a post-processing time that the envelope reaches its final state.
Callback Types
- Envelope Callback
- Envelope Status Callback
- Workstep Event Callback
- Draft Callbacks
Envelope Callback
This is the basic callback (“CallbackUrl”: “”), which is fired if the envelope reaches a final state (completed, rejected). If you integrate eSAW, please have a look at the Envelope Status Callback (directly below documented), because it might deliver more details about the envelope and might so be more useful for integrating.
Placehoder
- ##EnvelopeId##
- ##Action##
- envelopeFinished : when an envelope was finished (completed or rejected)
Sample:
https://www.mycallback.at?envelope=##EnvelopeId##
Envelope Status Callback
Envelopes status callbacks (“StatusUpdateCallbackUrl”: “”,) are fired, based on envelope events/actions. There are also detailed callbacks available based on events.
Consider, that our system expects the full callback url, including the parameter list you expect, with the placeholders that should be replaced by values at runtime. You can also add your own paramter for that envelope (e.g. internal references). Moreover, on our shared SaaS environments only HTTPS (port 443) callbacks are allowed.
Placehoder for callback URL:
- ##EnvelopeId##
- ##Action##
- workstepFinished : when the workstep was finished
- workstepRejected : when the workstep was rejected
- workstepDelegated : whe the workstep was delegated
- workstepOpened : when the workstep was opened
- sendSignNotification : when the sign notification was sent
- envelopeExpired : when the envelope was expired
- workstepDelegatedSenderActionRequired : when an action from the sender is required because of the delegation
Consider, that our system expects the full callback url, including the parameter list you expect, with the placeholders that should be replaced by values at runtime. You can also add your own paramter for that envelope (e.g. internal references). Moreover, on our shared SaaS environments only HTTPS (port 443) callbacks are allowed.
Sample:
https://www.mycallback.at?envelope=##EnvelopeId##&action=##Action##
Sample with custom parameter “internalid“:
https://www.mycallback.at?envelope=##EnvelopeId##&action=##Action##&internalid=1234
Workstep Event Callbacks
The workstep event callbacks are specific event callbacks fired on events caused by the underlying "SIGNificant Server Platform" component, but also routed through the notification system of eSignAnyWhere. Those callbacks inform in a way more detailled way about the workstep events - but note that those events are not necessarily time-synced to the envelope events. To trigger activities on the eSignAnyWhere API, always consider the envelope or envelope status callbacks.