Partner API

In Secured Signing account system, we have following kinds of accounts:

• Partner account: this account is right for you. Through it, you can manage your API settings and accounts for your client companies and their users.
• company account: this account is for your client company. You can group and manage this client’s users. There’re 2 types for client company account:
  • Type A: this type is suitable for large company / enterprise, who may have branches, sectors or subsidiary. It will use Enterprise Edition plan
  • Type B: this type is described for small company, who may want simple structure and easy payment method. It will use Pay as you Go or Team Edition plan
• branch account: this account is for branches, sectors or subsidiary of type A client company account. It’s called membership under an Enterprise Edition plan.
• user account: this user account is for your clients’ staff user. It represents the end users who own and send the document to sign.

You can manage all these accounts via Secured Signing Partner API. By classifying and grouping these different kinds of accounts / users, you can have a clear view of by who what can be done, instead of a mess.

By contacting Secured Signing and tell us what you’re looking for, we will setup your partner account properly. If you want to use our partner API, you will get:

• API Key
• API Secret
• Callback Url: usually can be your company domain
• And the support to master the API.

Before using Secured Signing Partner API, you may have a look at Additional 1 Understand Secured Signing API Authentication at bottom.

Create a company account (Type A)

Before performing this action, please refer to Addition 2 Get Access Token for partner account firstly.

This API will create a new company account with a default branch account.

The creating company account API request:

API Endpoint:

POST https://api.securedsigning.com/web/v1.4/Account/Membership

Headers:

please refer to Additional 1 Understand Secured Signing API Authentication.

Body in JSON format (required properties only):

{
    "TermsOfUse": true,
    "Company": {
        "CompanyName": "",
        "StreetAddress": "",
        "City": "",
        "Country": "", //full country name, such as New Zealand, United States, not nz or us.
        "CountryCode": "", //international phone code, such as 64 for New Zealand, 1 for United States.
        "PhoneNumber": "",
        "ContactFirstName": "",
        "ContactLastName": "",
        "ContactEmail": "",
        "GMTOffset": 0 //The timezone difference in minutes, such as 780 for New Zealand Lightsaving Time, -480 for Pacific Time.
    }
}

Response in JSON format:

{
    "MembershipCode":"GMP9647",
    "Reference":"07904722718019222...164233115199186023189",
    "UpdateKey":"07418701004404012...514916199105219246133",
    "Result":"UpdateCC"
}

Please save Membership Code, Reference, Update Key for this company account. You need them to get access token on behalf of the client company.

Complete the payment for company account

If it’s a new client company account, you need to setup its payment. Visit update URL below in a browser

https://www.securedsigning.com/Utilities/LinkAccess.aspx?Key=[UpdateKey]

Create a client company account (Type B)

Before performing this action, please refer to Addition 2 Get Access Token for partner account firstly.

The creating company account API request:

API Endpoint:

POST https://api.securedsigning.com/web/v1.4/Account/AddAccount

Headers:

please refer to Additional 1 Understand Secured Signing API Authentication.

Body in JSON format:

{
    "User": {
        "FirstName": "",
        "LastName": "",
        "Email": "" //Basic information only, please set as much information as you can.
    },
    "Plan":{        //can be null if client chooses Pay As You Go plan, maximum user up to 10.
        "PlanUsers":5,   //maximum users can be added to this client account.
        "PlanDocuments":200 //maximum documents can be used per month for all user.
    },
    "GMT":0
}

Response in JSON format:

{
    "ConnectKey":"0741870100440401...28195165045067116199105219246133",
    "Result":"OK"
}

This API will create the client company account with an admin user, who will receive an activation email and need to do setup in Secured Signing before any action.

Use connect key to get access token for this admin user account when performing action on its behalf. It can only be used once. Please refer to Additional 4 Get Access Token for user account to know how to get and refresh the access token.

Add a user to your client company account

Before performing this action, please refer to Additional 3 Get Access Token for company account firstly.

The Add User API request:

API Endpoint:

POST https://api.securedsigning.com/web/v1.4/Account/AddMembershipUser

Headers:

please refer to Additional 1 Understand Secured Signing API Authentication.

Body in JSON format (required properties shown only, please refer to Additional 6 Full User object details.):

{
    "User":{
        "FirstName":"",
        "LastName":"",
        "Email":""
    },
    "ClientReference":""
}

Response in text, which is a key for this user account:

18423119919508...2202031045067116199105219246133

Use this key to get access token for this user account when performing action on its behalf. It can only be used once. Please refer to Additional 4 Get Access Token for user account to know how to get and refresh the access token.

Add user to your client company account

Before performing this action, please refer to Additional 4 Get Access Token for user account firstly to get Access Token for admin user of client account.

The Add User API request:

API Endpoint:

POST https://api.securedsigning.com/web/v1.4/Account/AddUser

Headers:

please refer to Additional 1 Understand Secured Signing API Authentication.

Body in JSON format (required properties only, please refer to Additional 6 Full User object details.):

{
    "User":{
        "FirstName":"",
        "LastName":"",
        "Email":""
    },
    "GMT":0
}

Response in text, which is a key for this user account:

{
    "ConnectKey":"074187010044040123...228195165045067246133",
    "Result":"OK"
}

Use this key to get access token for this user account when performing action on its behalf. It can only be used once. Please refer to Additional 4 Get Access Token for user account to know how to get and refresh the access token.

The API Authentication consists of two parts: OAuth2 and Signature.

They make the API request safe and controllable, which benefits you and your clients.

OAuth2

By authenticated with OAuth 2, you are able to call all API functions on behalf of your clients’ staff and themselves.

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.

If you’re verifying authentication on a sandbox organization, use “www.dsx.co.nz” instead of “www.securedsigning.com” in all the OAuth endpoints listed above.

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);

API Request Headers

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

As we can see, enterprise account has more power than client and user account. For safety, you need to get access token every time you call API on behalf of enterprise account.

Please tell Secured Signing what clients you have or discuss with use what you need, so that we can enable the right features for you.

For this special API, please set OAuth2 Token Request body as blow:

Use POST method to send HTTP form format to OAuth2 Token Endpoint. The request would look like:

POST https://www.securedsigning.com/api/oauth2/token HTTP/1.1
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&client_id=...&client_secret=...&redirect_uri=...&client_credential_type=special_feature&feature=MembershipManagement

Get access token from response, which is in JSON format:

{
    "access_token":"[Access Token]",
    "token_type":"bearer",
    "expires_in":86400,
    "scope":"Account"
}

As we can see, client account has more power than user account. For safety, you need to get access token every time you call API on behalf of client account.

For this special API, please set OAuth2 Token Request body as blow:

Use POST method to send HTTP form format to OAuth2 Token Endpoint. The request would look like:

POST https://www.securedsigning.com/api/oauth2/token HTTP/1.1
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&client_id=...&client_secret=...&redirect_uri=...&client_credential_type=membership_authentication&membership_code=...&membership_reference=...

Get access token from response, which is in JSON format:

{
    "access_token":"[Access Token]",
    "token_type":"bearer",
    "expires_in":86400,
    "scope":"Account"
}

Get OAuth2 access token from existing user account

Existing user accounts means that users have already signed up in Secured Signing. They can also connet their user account to your service through a standard OAuth 2 authorization flow.

Please set OAuth2 Authorise Request URL as blow:

Supported scopes list:

Use GET method to send to OAuth2 Authorise Endpoint. The request would look like:

GET http://www.securedsigning.com/api/oauth2/authorize?response_type=code&client_id=...&redirect_uri=...&scope=... HTTP/1.1

User will be redirected to Secured Signing, they need to login and authorise and then redirect back to your service.

Get authorization code from query part of callback URL

[CallbackURL]?code=whx0...wHd5

Use this authorization code to access Secured Signing OAuth 2 Token endpoint to get access token.

Please set OAuth2 Token Request URL as blow:

Use POST method to send request to OAuth2 Token Endpoint. The request would look like:

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

grant_type=authorization_code&client_id=...&client_secret=...&redirect_uri=...&code=...

Get access token from response, which is in JSON format:

{
    "access_token":"",
    "token_type":"bearer",
    "expires_in":86400,
    "refresh_token":"",
    "scope":""
}

Please save the new access token for this user to perform operations on its behalf.

Get OAuth2 access token from new user account

Please set OAuth2 Authorise Request URL as blow:

Use GET method to send to OAuth2 Authorise Endpoint. The request would look like:

GET http://www.securedsigning.com/api/oauth2/authorize?response_type=code&client_id=...&redirect_uri=...&scope=...&Key=... HTTP/1.1

This URL will have to do 302 redirects to get final response. So your HTTP client should support redirect.

Get access token from response, which is in JSON format:

{
    "access_token":"",
    "token_type":"bearer",
    "expires_in":86400,
    "refresh_token":"",
    "scope":""
}

Please save access and refresh token for this user to perform operation on its behalf.

Refresh token for account

If account’s access token expired, you can use its refresh token to get a new access token. It’s a standard OAuth2 refresh token process.

Please set OAuth2 Token Request URL as blow:

Use POST method to send to OAuth2 Token Endpoint. The request would look like:

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

grant_type=refresh_token&client_id=...&client_secret=...&redirect_uri=...&refresh_token=...

Get access token from response, which is in JSON format:

{
    "access_token":"",
    "token_type":"bearer",
    "expires_in":86400
}

Please save the new access token for this user to perform operations on its behalf.

With access token of user account, you can call Secured Signing API, e.g. uploading document or sending Smart Tag. Please refer to API Documentation page for a full list of API Seucred Signing supported.

Here’s a sample how to get a user account information from Secured Signing.

The Account Infomation API request:

API Endpoint:

GET https://api.securedsigning.com/web/v1.4/Account/Info

Headers:

please refer to Additional 1 Understand Secured Signing API Authentication.

Response in JSON format, which is infomation for this user account:

{
    "Actived":true,
    "Locked":false,
    "Email":"...",
    "Name":"...",
    "PlanName":"...",
    "PlanType":"...",
    "DocumentRemain":0,
    "DocumentUsed":8
}

To call other API functions, set the headers and follow the API request format to fill data, then send request to get response.