OAuth 2.0
- List Businesses
- Create Document
- Create Template
- Use Template
- Get Document / Template
- List Documents
- List Templates
- Send Reminder
- Reassign Signer
- Delete Document
- Trash Document / Template
- Cancel Document
- Download Original PDF
- Download Final PDF
- Upload File
- Get Bulk Sending Blank CSV
- Validate Bulk Sending CSV
- Create Bulk Job
- Get Bulk Job by id
- Get Bulk Job Status by id
- Get Bulk Job Documents by id
- Get Bulk Jobs list
- Audit Log
- Errors
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. |
Getting your OAuth Token
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://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.
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. The business_id has to be specified within your API request.