* For Partner API, please click here.

* For previous API version, please click here.

Getting Started

Add an API Account by logging in to your account

Navigate to My Account - > My Settings -> API Settings

Add an API key using the button at the top. This will generate an API account, with configurable settings for your connection.

* It is important to specify a name as well as a domain from where the API requests will come.

Using the API

The API is Rest based, and can be found at Documentation tab.

Response Codes

The following response codes apply to all requests. Check each request type in the list below for more response codes specific to that request.

Status Code Meaning
200 OK The request was processed successfully
401 Unauthorized Authentication failed or the Authenticate header was not provided
404 Not Found The URI does not match any of the recognised resources

Response and Request Data Formats

Supported Request Formats

Use the Content-Type header to specify the format your data is in.

  • JSON: application/json
  • Multipart Form Data: multipart/form-data

Supported Response Formats

Use the Accept header to specify the output desired format. If you can’t set that header, use the format parameter in the query string. The format parameter takes precedence over the Accept header.

  • JSON: application/json

Getting Started Walk-throughs

Please feel free to Contact Us for any questions or help

Authentication

The REST API uses stateless authentication using OAuth 2.0 with HMAC SHA-256.

OAuth 2.0

By authenticated with OAuth 2.0, you are able to call all API functions on behalf of the authorized user.

OAuth endpoints are the URLs you use to make OAuth authentication requests to Secured Signing.

You need to use the correct Secured Signing OAuth endpoint when issuing authentication requests in your application. The primary OAuth endpoints are:

  • For authorization: https://www.securedsigning.com/api/oauth2/authorize
  • For token requests: https://www.securedsigning.com/api/oauth2/token
  • For revoking OAuth tokens: https://www.securedsigning.com/api/oauth2/revoke

All endpoints require secure HTTP (HTTPS). Each OAuth flow defines which endpoints you need to use and what request data you need to provide.

OAuth 2.0 Authorization Code Flow (Web Server OAuth Authentication Flow)

The authorization code flow is used by applications that are hosted on a secure server, e.g. web server. You can use code challenge and verifier values in the flow to prevent authorization code interception.

In this flow, the client application requests the authorization server to redirect the user to Secured Signing that authorizes the user and sends the application an authorization code. The application uses the authorization code to request an access token. The following shows the steps for this flow.

     +----------+
     | Secured  |
     | Signing  |
     |  User    |
     +----------+
          ^
          |
         (B)
     +----|-----+          Client Identifier      +---------------+
     |         -+----(A)-- & Redirection URI ---->|               |
     |   Web    |                                 |    Secured    |
     | Browser -+----(B)-- User authenticates --->|    Signing    |
     |          |                                 |               |
     |         -+----(C)-- Authorization Code ---<|               |
     +-|----|---+                                 +---------------+
       |    |                                         ^      v
      (A)  (C)                                        |      |
       |    |                                         |      |
       ^    v                                         |      |
     +---------+                                      |      |
     |         |>---(D)-- Authorization Code ---------'      |
     |  Your   |          & Redirection URI                  |
     |  App    |                                             |
     |         |<---(E)----- Access Token -------------------'
     +---------+       (w/ Optional Refresh Token)
                    

The application redirects the user to Secured Signing authorization endpoint. The following parameters are required:

Key Value
response_type Required must be "code"
client_id Required Your API Key
redirect_uri Required Your Callback URL
scope Required [The things this account can do, e.g. Basic to get account details, WeSign to do We Sign process]
See full list below.
state Optional any additional URL-encoded data to be returned in the callback URL after approval

Supported scopes list, scope is case sensitive:

Scope Description
Basic Basic Profile - Fetch information about your Secured Signing account, such as your price plan, account status etc.
ISign I Sign - Sign documents as a sole Signatory.
WeSign We Sign - Invite other people to sign documents.
SmartTag Smart Tag - Send documents with Smart Tags.
FormDirect Form Direct - Fetch and send your online Form Direct forms.
FormFiller Form Filler - Fill in online forms and sign.

An example authorization request:

https://www.securedsigning.com/api/oauth2/authorize?response_type=code&client_id=3MVG9lKc...9LLM82Hn&redirect_uri=https%3A%2F%2Fwww.example.com%2Fcallback&state=mystate&scope=Basic%20SmartTag
                    

The user logs into Secured Signing. The user is interacting with the authorization endpoint directly, so the application never sees the user’s credentials. After successfully logging in, the user is asked to authorize the application.

After Secured Signing confirms that the client application is authorized, the web browser is redirected to the callback URL specified by the redirect_uri parameter. Secured Signing appends authorization information to the redirect URL with the following values:

Key Value
code Authorization code
state state value passed before

An example authorization response:

https://www.example.com/callback?code=aWek...fhc4w%3D%3D&state=mystate
                    

The application extracts the authorization code and passes it in a request to Secured Signing token endpoint for an access token. This request is a POST request. The following parameters are required:

Key Value
grant_type Required must be "authorization_code"
client_id Required API Key
client_secret Required API Secret
redirect_uri Required Callback URL
code Required Authorization Code

An example access token POST request:

POST https://www.securedsigning.com/api/oauth2/token HTTP/1.1

grant_type=authorization_code&code=aWek...fhc4w%3D%3D&client_id=33MVG9lKc...9LLM82Hn&client_secret=1955...41571&redirect_uri=https%3A%2F%2Fwww.example.com%2Fcallback
                    

If this request is successful, the server returns a response body that contains the following:

Key Value
access_token Access Token
refresh_token Refresh Token
expires_in Access Token lifetime
token_type Bearer
scope authorized scopes

An example access token POST response:

{
    "expires_in":"86400",
    "refresh_token":"5Aep8614...yg==",
    "token_type":"Bearer",
    "scope":"Basic SmartTag",
    "access_token":"00Dx00...9JksNEkWUl"
}
                    

The application uses the provided access token and refresh token to do action on behalf of the user.

OAuth 2.0 Implicit Flow (User-Agent OAuth Authentication Flow)

The OAuth 2.0 Implicit authentication flow is used by client applications (consumers) residing in the user’s device. This could be implemented in a browser using a scripting language such as JavaScript, or from a mobile device or a desktop application. These consumers cannot keep the client secret confidential.

In this flow, the client application requests the authorization server to redirect the user to Secured Signing which is capable of extracting the access token and passing it back to the application. The following shows the steps for this flow.

     +----------+
     | Secured  |
     | Signing  |
     |  User    |
     +----------+
          ^
          |
         (B)
     +----|-----+          Client Identifier     +---------------+
     |         -+----(A)-- & Redirection URI --->|               |
     |   Web    |                                |     Secured   |
     | Browser -|----(B)-- User authenticates -->|     Signing   |
     |          |                                |               |
     |          |<---(C)--- Redirection URI ----<|               |
     |          |          with Access Token     +---------------+
     |          |            in Fragment
     |          |                                +---------------+
     |          |----(D)--- Redirection URI ---->|   Web-Hosted  |
     |          |          without Fragment      |    Resource   |
     |          |                                |     e.g.      |
     |     (F)  |<---(E)------- Script ---------<|  ISign/WeSign |
     |          |                                +---------------+
     +-|--------+
       |    |
      (A)  (G) Access Token
       |    |
       ^    v
     +---------+
     |         |
     |  Your   |
     |  App    |
     +---------+
                    

The application redirects the user to Secured Signing authorization endpoint. The following parameters are required:

Key Value
response_type Required must be "token"
client_id Required Your API Key
redirect_uri Required Your Callback URL
scope Required [The things this account can do, e.g. Basic to get account details, WeSign to do We Sign process]
See full list below.
state Optional any additional URL-encoded data to be returned in the callback URL after approval

An example authorization request:

https://www.securedsigning.com/api/oauth2/authorize?response_type=token&client_id=3MVG9lKc...9LLM82Hn&redirect_uri=https%3A%2F%2Fwww.example.com%2Fcallback&state=mystate&scope=Basic%20SmartTag
                    

The user logs into Secured Signing. The user interacts with the authorization endpoint directly, so the application never sees the user’s credentials.

Once authorization is granted, the authorization endpoint redirects the user to the redirect URL with following values:

Key Value
access_token Access Token
expires_in Access Token lifetime
token_type Bearer
scope authorized scopes
state state value passed before

An example access token response:

{
    "expires_in":"86400",
    "token_type":"Bearer",
    "scope":"Basic SmartTag",
    "access_token":"00Dx00...9JksNEkWUl"
}
                    

The application uses the provided access token to do action on behalf of the user.

OAuth 2.0 Refresh Token Flow

The OAuth 2.0 Authorization Code Flow (Web Server OAuth Authentication Flow) provides a refresh token that can be used to obtain a new access token.

Access tokens have a limited lifetime specified by the session timeout in Secured Signing. If an application uses an expired access token, a “Session expired or invalid” error is returned.

The client application obtains a new access token by sending a POST request to the token request endpoint with the following request parameters:

Key Value
grant_type Required must be "refresh_token"
client_id Required API Key
client_secret Required API Secret
refresh_token Required Refresh Token

An example refresh token POST request:

POST https://www.securedsigning.com/api/oauth2/token HTTP/1.1

grant_type=refresh_token&refresh_token=aWek...fhc4w%3D%3D&client_id=33MVG9lKc...9LLM82Hn&client_secret=1955...41571
                    

Once Secured Signing verifies the refresh token request, it sends an access token response as above to the application.

API Signature

API signature provides more safety for each API request, used as a stateless authentication with HMAC SHA-256.

All requests to resources (excluding the schema pages) must be accompanied by the correct Authentication headers as per this specification.

Secured Signing custom headers

  • X-CUSTOM-API-KEY : This is your ApiKey which can be generated from "My Settings" in the Account page
  • X-CUSTOM-SIGNATURE : This is a HMAC SHA-256 hash of a string of properties outlined below using your api secret which is generated at the same time as your ApiKey
  • X-CUSTOM-DATE : This is a Unix timestamp of the time you made the request. We allow a slight buffer on this in case of any time sync issues.
  • X-CUSTOM-NONCE : A randomly generated string of your choice. Ensure it is unique to each request, and no more than 32 characters long.

HTTP standard headers

  • Referer: The address where the request originated. Please specify the Callback URL.
  • Authorization: The OAuth2 access token with token type "Bearer", i.e. "Bearer [access token]"

The signature header value to be hashed is created using the following properties ApiKey, time stamp and nonce as show below

ApiKey\n
timestamp\n
nonce

Please use '\n' as shown above.

After the string is created above, it is hashed using HMAC SHA-256 using your API Secret. It must be Base64 string encoded before adding it to the header.

e.g. In JavaScript (We are using Googles CryptoJS library for the hashing and Base64 encoding)

var hash = CryptoJS.HmacSHA256(apiKey + '\n' + timestamp + '\n' + nonce, apiSecretKey);
var hashInBase64 = CryptoJS.enc.Base64.stringify(hash);

Our client SDK libraries perform these functions for you, as well as adding the headers automatically.

Summary

So for each API request, you need to set following headers

Key Value
Content-Type application/json
X-CUSTOM-API-KEY [Your API Key]
X-CUSTOM-DATE [Unix timestamp of the time you made the request]
X-CUSTOM-NONCE [A randomly generated unique string]
X-CUSTOM-SIGNATURE [Authorization signature]
Referer [Your Callback URL]
Authorization Bearer [Access Token]

Client SDK

The client SDK provides an encapsulated library exposing simple to use methods that hide the complexity of integrating with our Rest API.

* The provided SDKs' codes are on Github. Fork me on GitHub

JavaScript

We also host the JavaScript version from our hosting.

Please add the following script reference in the header section of your page

<script data-main="https://api.securedsigning.com/web/v1.4/client/scripts/main" src="https://api.securedsigning.com/web/v1.4/client/scripts/require.js"></script>

To initialise the JavaScript SDK library

First create a config object as shown below


var config = {
    "apiKey": <YOUR API KEY HERE>,
    "baseUrl": "https://api.securedsigning.com/web",
    "version": "v1.4",
    "secret": <YOUR API SECRET HERE>,
    "scope": <SCOPEs REQUIRED>
};

Next initialise the library.

We have provided a function SSApiLoaded that executes when the scripts have loaded if you are using our hosted JavaScript libraries

function SSApiLoaded() {
    securedsigning = new SecuredSigning(config); 
};

Before any action, get OAuth2 access token using OAuth 2 Implicit flow.

We have provided a function securedsigning.getAccessToken to help you to start the process.

An SDK method call normally takes 3 parameters

  1. requestData: the data required for performing the task
  2. onSuccess: Callback function to handle a successful request
  3. onError: Callback function to handle any errors

An example

securedsigning.sendSmartTagDocument(smartTagData, function (result) {
    console.log(result);
},function (error) {
    console(error);
});

.NET

You can view the source code on GitHub HERE

Install our .NET client SDK

SecuredSigning.Client PM> Install-Package SecuredSigning.Client

This library has the following dependencies Newtonsoft.Json, ServiceStack.Client.Signed, ServiceStack.Text.Signed and ServiceStack.Interfaces

To initialise the library call the constructor

var client = new ServiceClient("https://api.securedsigning.com/web","v1.4", <YOUR API KEY HERE>, <YOUR API SECRET HERE>, <YOUR CALLBACK URL HERE>);

Before any action, get OAuth2 access token using OAuth 2 Authorization Code flow.

We have provided a series of functions to help you to complete the OAuth 2 process.

  • OAuth2.CreateAuthorizeRequest to generate the authorize request URL.
  • OAuth2.HandleAuthorizeCallback to handle authorize callback from Secured Signing.
  • OAuth2.GetToken to get access token.
  • OAuth2.RefreshToken to refresh access token.
  • OAuth2.RevokeToken to revoke access token.

We have provided data objects for the requests e.g.


[Schema("EmailTemplate")]
public class EmailTemplate
{
    public string Reference { get; set; }

    public string Name { get; set; }
}

An example of a function call

var forms = client.getFormList();

Other Languages

We have provided more client SDKs of different programing languages as well, with their source codes on GitHub.

UI SDK

The UI SDK is provided as part of the JavaScript sdk. Please add the scripts as below

<script data-main="https://api.securedsigning.com/web/v1.4/client/scripts/main" src="https://api.securedsigning.com/web/v1.4/client/scripts/require.js"></script>

Initialising SDK

To initialise the JavaScript SDK library

First create a config object as shown below


var config = {
    "apiKey": <YOUR API KEY HERE>,
    "baseUrl": "//api.securedsigning.com/web",
    "version": "v1.3",
    "secret": <YOUR API SECRET HERE>,
    "scope": <SCOPEs REQUIRED>
};

Get access token

You can use our login control to start OAuth 2 process.

Use the following JavaScript function passing in a DOM element id for the login button

securedsigning.CreateLogin("login");
                    

Uploading a document

You can use our uploader to add a document for signing

Use the following JavaScript function passing in a DOM element id for the upload button

This then on Success starts an ISign or WeSign process

 securedsigning.CreateUpload(<DOM ELEMENT ID>, function(data) {
                ISign(data.Reference);
                //WeSign(data.Reference);
            },function (error) {
      alert(error);
});

After a document is submitted, a reference will return.

Embedding html resources

I Sign

For an I Sign signing process, the OAuth 2 scopes are "Basic" and "ISign".

This embeds a signing resource in a DOM element with the id of 'content'.

function ISign(ref) {
    var request = {
        DocumentReference: ref
    };
            
    securedsigning.getISignResource(request, "content", function (error) {
    });
}
We Sign

For an We Sign signing process, the OAuth 2 scopes are "Basic" and "WeSign"

This embeds a signing resource in a DOM element with the id of 'content'.

function WeSign(ref) {
    var request = {
        DocumentReference: ref
    };
            
    securedsigning.getWeSignResource(request, "content", function (error) {
    });
}

Download a sample webpage HERE.

API Documentation