Secured Signing API With OAuth 2

  1. Getting Started
  2. Authentication
  3. Client & UI SDK
  4. Documentation
* For Partner API, please click here.

* For API Without OAuth 2 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.

StatusCodeMeaning
200OKThe request was processed successfully
401UnauthorizedAuthentication failed or the Authenticate header was not provided
404Not FoundThe 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://securedsigning.com/api/oauth2/authorize
  • For token requests: https://securedsigning.com/api/oauth2/token
  • For revoking OAuth tokens: https://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_typeRequiredmust be “code”
client_idRequiredYour API Key
redirect_uriRequiredYour Callback URL
scopeRequired[The things this account can do, e.g. Basic to get account details, WeSign to do We Sign process]
See full list below.
stateOptionalany additional URL-encoded data to be returned in the callback URL after approval

Supported scopes list, scope is case sensitive:

ScopeDescription
BasicBasic Profile – Fetch information about your Secured Signing account, such as your price plan, account status etc.
ISignISign – Sign documents as a sole Signatory.
WeSignWeSign – Invite other people to sign documents.
SmartTagSmart Tag – Send documents with Smart Tags.
FormDirectForm Direct – Fetch and send your online Form Direct forms.
FormFillerForm Filler – Fill in online forms and sign.
BillingBilling Management – Manage account invoices and details.

An example authorization request:

https://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:

KeyValue
codeAuthorization code
statestate 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_typeRequiredmust be “authorization_code”
client_idRequiredAPI Key
client_secretRequiredAPI Secret
redirect_uriRequiredCallback URL
codeRequiredAuthorization Code

An example access token POST request:

POST https://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:

KeyValue
access_tokenAccess Token
refresh_tokenRefresh Token
expires_inAccess Token lifetime
token_typeBearer
scopeauthorized 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_typeRequiredmust be “token”
client_idRequiredYour API Key
redirect_uriRequiredYour Callback URL
scopeRequired[The things this account can do, e.g. Basic to get account details, WeSign to do We Sign process]
See full list below.
stateOptionalany additional URL-encoded data to be returned in the callback URL after approval

An example authorization request:

https://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:

KeyValue
access_tokenAccess Token
expires_inAccess Token lifetime
token_typeBearer
scopeauthorized scopes
statestate 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_typeRequiredmust be “refresh_token”
client_idRequiredAPI Key
client_secretRequiredAPI Secret
refresh_tokenRequiredRefresh Token

An example refresh token POST request:

POST https://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

KeyValue
Content-Typeapplication/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]
AuthorizationBearer [Access Token]

Client & UI 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://securedsigning.com/web/v1.4/client/scripts/main" src="https://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://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.JsonServiceStack.Client.SignedServiceStack.Text.Signed and ServiceStack.Interfaces

To initialise the library call the constructor

var client = new ServiceClient("https://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://securedsigning.com/web/v1.4/client/scripts/main" src="https://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.4",
    "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.getWeSignResource2(request, "content", function (error) {
    });
}

The invitees details can be pre-configured when setting up the WeSign request

function WeSign(ref) {
    var request = {
        DocumentReference: ref,
        //other options
        DisableBroadcast: false,
        SelectOnly: false,
        NotifyUrl:'',
       
        Invitees: [{
                    firstname: 'User1',        //first name
                    lastname: 'Test',          //last name
                    email: 'user1@sample.com'  //email address
                }, {
                    firstname: 'User2',
                    lastname: 'Test',
                    email: 'user2@sample.com'
                }]
           
    };

    securedsigning.getWeSignResource2(request, "content", function (error) {
    });
}

And fields from your system as well

function WeSign(ref) {
    var request = {
        DocumentReference: ref,
        //other options
        DisableBroadcast: false,
        SelectOnly: false,
        NotifyUrl:'',
       
        Integration: {
                    Name: 'Integration 1',                      //your integration name
                    FieldGroups: [{                             //your integration records/objects
                        GroupID: "Account__Fields__a1",             //record unique ID
                        GroupIcon: "",                              //record icon
                        GroupLabel: "Account Fields",               //record label
                        GroupName: "Account",                       //record name
                        GroupRecordID: "a1",                        //record ID
                        GroupRecordLabel: "Company A",              //record display name
                        Fields: [{                                  //record fields
                            ControlType: 0,                             //field type, values see below
                            FieldLabel: "Account Name",                 //field label
                            FieldName: "Name",                          //field name
                            FieldType: "STRING",                        //field type in your system
                            FieldValue: "Company A"                     //field value
                        }, {
                            ControlType: 5,
                            FieldLabel: "Account Type",
                            FieldName: "Type",
                            FieldType: "PICKLIST",
                            FieldValue: "Technology Partner",
                            Options: [                                  //field options, e.g. for dropdown list
                                {
                                    Label: "Technology Partner",            //option label
                                    Value: "Technology Partner"             //option value
                                },
                                {
                                    Label: "Other",
                                    Value: "Other"
                                }]
                        }]
                    }, {
                        GroupID: "Contact__Fields__b1",
                        GroupIcon: "",
                        GroupLabel: "Contact Fields",
                        GroupName: "Contact ",
                        GroupRecordID: "b1",
                        GroupRecordLabel: "Peter Green",
                        Fields: [{
                            ControlType: 0,
                            FieldLabel: "Last Name",
                            FieldName: "LastName",
                            FieldType: "STRING",
                            FieldValue: "Green"
                        },
                        {
                            ControlType: 0,
                            FieldLabel: "First Name",
                            FieldName: "FirstName",
                            FieldType: "STRING",
                            FieldValue: "Peter"
                        }]
                    }]
                }

           
    };

    securedsigning.getWeSignResource2(request, "content", function (error) {
    });
}

Supported Control types

Text
0
Multi Line Text
1
Check Box
3
Radio Button
4
Dropdown List
5
Date
6
Email
7
Number
8
Multiple Select Dropdown List
9
Phone
15
Integer
16

Download a sample webpage here.

Documentation

Do you need anything else?