OAuth 2.0

Using OAuth you will be able to make requests to the Xodo Sign API (e.g. send out a document for signature) on behalf of other Xodo Sign users. To do so, you will be required to set up an app and register it within your Xodo Sign account. Once your app has been approved, anyone using your app will be able to connect it to their Xodo Sign account, granting you authorization to perform Xodo Sign action on their behalf.

App Registration

The first step to using OAuth is setting up your app within the Xodo Sign control panel. Navigating to the top left dropdown menu and selecting "Developer" will take you to the page where apps can be added. Near the bottom of the page, click "Register New App" and enter the following data:

OAuth Credentials

Once your app has been approved, you will be provided with your client ID and secret key. These credentials will be required for your app to authenticate with Xodo Sign and make it possible for end-users to authenticate with your app.

User Authorization

In order to be able to make API requests on behalf of other users, they will need to give you authorization to do so. This authorization is given using an authorization page, which comes standard with each approved app.

Below you'll see an authorization page URL. Simply append your values for the parameters client_id and state and you can get started redirecting your users to this page in order to let them authorize their Xodo Sign account with your app.

Authorization page URL:

https://app.eversign.com/oauth/authorize?client_id=YOUR_CLIENT_ID&state=YOUR_STATE_VALUE

Once your end-users click on the "Authorize" button, they will be redirected to the OAuth Callback URL you've specified for your app. Your OAuth Callback URL will be appened a code parameter containing a code you require to get your OAuth Token later on, and the state parameter that was used in the authorize URL. If the end-user declines the authorization, only the state parameter will be added.

Finally, in order to retrieve the OAuth token you need to make a backend call with the code you retrieved via the user-callback. Make a multipart/form-data POST request to the following URL:

Token Request URL

https://app.eversign.com/oauth/token

POST Parameters (multipart/form-data)

client_id: "YOUR_CLIENT_ID",
client_secret: "YOUR_CLIENT_SECRET",
code: "YOUR_CODE",
state: "YOUR_STATE_PARAMETER"

API Response

If successful, the Xodo Sign API will return a JSON array containing a number of response objects, including your OAuth Token:

{
  "access_token": "YOUR_OAUTH_TOKEN",
  "token_type": "Bearer",
  "expires_in": ""
  "state": "YOUR_STATE_TOKEN"
}

API Response Objects:

Making OAuth API Calls

Once you have retrieved your OAuth Token, you will be able to make API calls on behalf of your end-user. API requests made on behalf of your end-users are made using the oAuth Bearer token that you received during the authorization process instead of using a regular access key.

To make API requests on behalf of an OAuth authorized end-user, instead of appending your API Access Key (as you do with standard API requests for your account) you will be required to send the OAuth Token as a Bearer HTTP header along with your API request.

Authorization Header Format: Bearer [YOUR_OAUTH_TOKEN]

Below you will see an example API request made to the API's document endpoint to retrieve one of the end-users documents.

Example API Request

https://api.eversign.com/document
  ? business_id = 1
  & document_hash = j6yMcaF2gQAIIQ

API Response

If successful, the Xodo Sign API will return the entire document in JSON format. In order to see how this response looks like, please jump to the Get Document section.