Meet our new brand: eversign is now Xodo Sign! Learn more

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:

Field Description
App Name Enter your app's name here. This will be the name shown to users during authorization.
App Domain Enter your app's domain here.
Terms of Use URL Optional - you can enter a URL to your Terms of Service here.
Privacy Policy URL Optional - you can enter a URL to your Privacy Policy here.
oAuth Callback URL Enter the URL to which your user will be redirected after authorizing your app.
Webhook URL Optional - you can enter a URL to which the Xodo Sign API will send updates related to documents created using your app.
Who will be billed? Choose whether usage of your app should be billed to your account (App Owner) or your app's end-users (App User). Please note that documents created using oAuth integrations are treated as API requests and will be deducted from a user's available API request volume.
Approval of your app Most apps are approved and activated instantly, others may take up to 1 business day to get approved. If you'd like to enquire about the approval status of your app, let us know by contacting us using the web form.

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.

Key Description
Client ID Your app's Client ID, which is passed into the authorization URL for end-users.
Client Secret Your app's secret ID, which is used to retrieve an OAuth token.

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:
Parameter Description
state The (optional) state parameter is used to prevent CSRF and can be set to a value of your choice. This token will be used within the URL's state parameter throughout the entire OAuth flow and you should verify that it matches the expected value when getting an oAuth callback.

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.

Parameter Description
code This parameter is returned within the redirect URL once your end-users complete the authorization and are redirected to your OAuth Callback URL.

Getting your OAuth Token multipart/form-data HTTP POST

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 POST request to the following URL:

Token Request URL

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:

Response Object Description
access_token This object will contain your OAuth token.
token_type This object indicates which type of token is returned (type is always Bearer).
expires_in This object indicates the number of seconds in which the given OAuth token will expire. Currently, this object will always be empty as tokens do not expire.
state This object will return the state token for the current OAuth flow.

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

Access permissions Please note that you will only be able to access documents on your end-users' accounts that were created using your OAuth Token. Documents created by the end-user independently will not be visible to you via OAuth.
Primary Business Please note that Business Selection in OAuth API requests works the same way as in standard API requests. If no business_id is specified within your API request, your end-user's Primary Business will be used for the current API request.