Authenticating API Users

Authenticating API Users

To receive an authentication token needed for other DocumentNOW V3.0+ API calls, post the credentials to the /authentication/apiUser endpoint providing your actual values in the JSON object including the AssureSign user name (email address) of the user on whose behalf you are authenticating in the contextUsername value:

{    "request": {    "apiUsername": "NewAPIUser",    "key": "vY+ak1310/yTfjN8qhoxEkjN1bX1Ev99",    "contextUsername": "bob@mycompany.com",    "sessionLengthInMinutes": 60    }}

Note that Content-Type on all AssureSign REST methods should be set to application/json.  The response of a successful authentication will include a token

{    "token": "tokenvaluewillbelongandpresenthere"}

You may now use the token by setting an Authorization header on subsequent calls to V3.0+ endpoints.  Add the token in the form:

Authorization:bearer tokenvaluewillbelongandpresenthere

The full endpoint will be relative to the available API version being used.

For example https://account.assuresign.net/api/v3.5/authentication/apiUser

Further calls using the token operate in the context of an account, specified in an additional X-AS-UserContext request header you must add to calls if the user belongs to more than one account.  The Account Context Identifier can be accessed in your account settings, and should be applied after the AssureSign username (an email address) in the form:

X-AS-UserContext {username}:{DocumentNOW Account Context Identifier}

Getting the Token and Where to Put It

This will require two calls, one to get the token and one to use the token.

To get the token:

1) Ensure you’ve created the API user, have the API Username/Key, and have stored that someplace safely.

2) In the header of your REST code, ensure you've got these things set:

• Accept:application/json
• Content-Type:application/json

And in the body, be sure to replace each item in the example request below, displayed in italics with your information:

{ "request": { "apiUsername": "YourAPIUsername", "key": "TheKeyGeneratedAndSharedFromAPIUserCreation", "contextUsername": "youremail@address.com" }
}

This returns the token, which you will need to copy/paste/retain.


To use the token:
1) In the REST headers you send, ensure you've got these things set, explicitly.  Replace the items in italics with your organization's information:

• Accept: application/json
• Content-Type: application/json
• Authorization: Bearer PUTYOURTOKENHERE
• X-AS-UserContext: THEUserNameANDContextIDHere

In the body - your request.  An example can be found below:

{ "request": {  "templates": [ { "templateID": "EnterYourTemplateIDHere", "values": [ { "name": "Envelope Name", "value": "My Envelope" }, { "name": "EnvelopeOrderID", "value": "My Envelope Number" }, { "name": "DocumentOrderID", "value": "My Document Number" }, { "name": "Expiration Date", "value": "mm/dd/yyyy" }, { "name": "Language", "value": "en-US, fr-CA, or es-US" }, { "name": "Signer 1 Name", "value": "SendAPI W. Template" }, { "name": "Signer 1 Email", "value": "signatory@email.com" }, { "name": "Signer 1 Mobile Phone", "value": "123-456-7890" }, { "name": "Document Name", "value": "New Document Name", "files": [ { "fileToUpload": { "data": "EnterTheBase64DataForYourDocumentHere", "fileName": "SomeFileName.pdf" }, "extension": "pdf" } ], "overlayStartPage": 0 } ]  } ] }}