Secured Signing API With OAuth 2

1. Getting Started
2. Authentication
3. Client & UI SDK
4. Documentation

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.

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

• Getting Started – FormDirect
• Getting Started – ISign
• Getting Started – WeSign
• Smart Tag API Documentation

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:

Supported scopes list, scope is case sensitive:

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:

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:

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:

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:

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:

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:

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.

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

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

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.

• Java : JAR file GitHub Repository

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