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. |
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:
https://eversign.com/oauth/authorize?client_id=YOUR_CLIENT_ID&state=YOUR_STATE_VALUE
| 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
https://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:
| 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
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.
business_id has to be specified within your API request.