Back to API Docs

OAuth

OAuth2 is a protocol that allows external applications to request access to private accounts without requiring direct access to a user's account credentials. In place of using shared passwords, authorized apps are granted unique access tokens. Access tokens are revocable and may be used to the limit app privileges.

In order to use Emburse's OAuth endpoints, you'll first need to register your app. After registration, you'll be given a client_id and client_secret which may be used to generate access tokens for API authentication.

If you only need to generate an access token for your own account and don't intend on creating a third-party integration that can be used by other companies, an access_token for your own company's account can be created from your app's settings page.

For granting third-party app authorizations, Emburse supports two methods:

  • Web Authorization Flow – A company accountant or administrator is sent to a login page wherein authorization is granted and permissions are reviewed.
  • Password Credentials Flow – A user's account credentials are collected and submitted for validation. MFA (multi-factor authentication) questions may be asked. This method only supports granting read-only access to an account.

Web Authorization Flow

Step 1

Send the user to the “Request Authorization” page.

Before web authorizations are permitted, a list of approved OAuth2 redirect URLs must be set. Redirect URLs can be set from your app's settings page. The first redirect URL within this list will be used as the default redirect URL if none is specified when authorizing an app. Once your redirect URLs have been configured, you may begin requesting app authorizations by sending your users to Emburse's “Request Authorization ” page which is located at the following URL:

Authorization URL

get https://app.emburse.com/v1/oauth/authorize

This authorization page should be shown using the following GET parameters:

GET Param Description
response_type: required This value is always just "code".
client_id: required The client ID you received after registering your application.
redirect_uri: optional The URL that your users should be redirected to after authorization. If left out, your application’s default redirect URL will be used.
scope: optional A comma or space separated list of scopes that are required by your app. By default, if no scopes are specified, an app is granted read-only access to an account.

App approval from Emburse is required before the following scope values may be used:

  • accountant
  • admin
In addition, only administrators may grant app authorization whenever the admin scope is used.
state: optional An unguessable random string that will be passed back to your app. Should be used to protect against cross-site request forgery attacks.
Example Authorization URL
https://app.emburse.com/v1/oauth/authorize?response_type=code&client_id=0694aa4d-c1e9-49bf-a7a4-27a52f8f2b84&redirect_uri=https%3A%2F%2Fexample.com%2Fcallback&scope=admin

Step 2

Emburse redirects the user back to your site.

If access to the user's account is granted, Emburse will redirect the user back to your site using the provided redirect_uri and add a new GET parameter, code, which contains a temporary code that may be used to create an access token.

If a state was included within the original authorization request, the state will be passed back as well. For example, a user may be redirect back to your site using the following URL:

https://example.com/callback?code=G6OHz97o3RWsv7v957Jm44ny&state=IWLC6uYR4I

If the user declines your authorization request, the user will still be redirected back to your site; however, a code will not be provided.

Example Redirect URL
https://example.com/callback?code=G6OHz97o3RWsv7v957Jm44ny&state=IWLC6uYR4I

Step 3

Create an access token using the code.

Use the code from the callback URL to create an access token. A code may be exchanged for an access_token using the following API endpoint:

post https://api.emburse.com/v1/oauth/token

When creating an access token, the following parameters are required. Both "application/x-www-form-urlencoded" and "application/json" content types are accepted.

ParameterDescription
grant_type: required The value of this field should be authorization_code.
code: required The code contained within the GET parameter of the callback URL.
client_id: required Your app's client_id.
client_secret: required Your app's client_secret.
redirect_uri: option The redirect_uri value used for the initial request if one was provided.

If successful, a JSON object with an access_token will be returned. This access token may now be included within the Authorization header of Emburse API requests.

Example Request
curl "https://api.emburse.com/v1/oauth/token" -X POST -d "grant_type=authorization_code" -d "code=G6OHz97o3RWsv7v957Jm44ny" -d "client_id=CLIENT_ID" -d "client_secret=CLIENT_SECRET" -d "redirect_uri=https://example.com/callback"
Example Response
201 Created
{
  "access_token": "zTF0vvvwWi...",
  "scope": []
}

Password Credentials Flow

Step 1

Create an access token using an email address and password.

This authentication method may be used to gain read-only access to a company's account using a user's email address and password. MFA (multi-factor authentication) questions may be asked as part of the authentication process.

To begin, a user's email address and account password must first be collected, after which they may be used to create an access_token. A user's credentials should be posted to the following API endpoint:

Create Access Token

post https://api.emburse.com/v1/oauth/token

When creating an access token, the following parameters are required. Both "application/x-www-form-urlencoded" and "application/json" content types are accepted.

ParameterDescription
grant_type: required The value of this field should be password.
username: required User's email address.
password: required User's password.
client_id: required Your app's client_id.
client_secret: required Your app's client_secret.

If no MFA questions must be answered and valid user credentials are submitted, an access_token will be returned.

201 Created – HTTP status code if authorization is granted.

Multi-factor Authentication

If MFA questions must first be answered before app authorization is granted, an access_token will still be created; however, a 203 HTTP status code will be returned and a challenge will be added to the response.

203 Non-Authoritative Information – MFA required.

Until all challenge questions have answered, all other API endpoints requiring authentication will reject requests with a 401 Unauthorized status code. An access_token will be revoked if a challenge expires before its question has been answered.

Example Request
curl "https://api.emburse.com/v1/oauth/token" -X POST -d "grant_type=password" --data-urlencode "username=user@example.com" --data-urlencode "password=hunter2" -d "client_id=CLIENT_ID" -d "client_secret=CLIENT_SECRET"
No MFA Required
201 Created
{
  "access_token": "zTF0vvvwWi...",
  "scope": []
}
MFA Required
203 Non-Authoritative Information
{
  "access_token": "zTF0vvvwWi...",
  "scope": [],
  "challenge": {
    "key": "mfa.code",
    "url": "https://api.emburse.com/v1/...",
    "question": "Code sent to xxx-xxx-2010.",
    "expires_at": "2016-09-13T05:00:58Z"
  }
}

Step 2

Get challenge question.

When multi-factor authentication is required, a challenge question may be retrieved from the following API endpoint:

get https://api.emburse.com/v1/oauth/token/challenge

This endpoint returns a challenge object that contains a single question and an expiration date before which the question must be answered. An access_token must be included in the Authorization header of these requests.

Challenge Object

FieldDescription
key: The type of question being asked.
url: A fully-qualified URL for the challenge resource.
question: Text for the question that must be answered.
choices: optional If choices are available, an array of possible answers will be provided. Example:
["Webnotes, Inc.", "Crocodoc, Inc."]
expires_at: Expiration before which questions must be answered (ISO 8601 format).
Example Request
curl "https://api.emburse.com/v1/oauth/token/challenge" -H "Authorization: Token ACCESS_TOKEN"
Example Response
200 OK
{
  "key": "mfa.company",
  "url": "https://api.emburse.com/v1/...",
  "question": "Select a company.",
  "choices": [
    "Webnotes, Inc.",
    "Crocodoc, Inc."
  ],
  "expires_at": "2016-09-13T05:00:58Z"
}

Step 3

Submit challenge answer.

To answer a challenge question, the answer should be submitted to the following API endpoint:

post https://api.emburse.com/v1/oauth/token/challenge

When submitting an answer, both "application/x-www-form-urlencoded" and "application/json" content types are accepted. An access_token must be included in the Authorization header of these requests.

ParameterDescription
answer: required Answer to the challenge question.

Response Status Code

The response for a submission will use one of the following status codes:

  • 200 OK – No additional MFA questions must be answered. App authorization has been granted.
  • 203 Non-Authoritative Information – Follow-up questions must be answered. A new challenge exists.
  • 401 Unauthorized – The challenge has expired, and the current access_token has been revoked.
  • 403 Forbidden – An invalid answer has been submitted. The user may try submitting a different answer.

Resolve or Retry

An application should continually request questions and submit answers until either:

  • A 200 OK status code is returned after which app authorization has been granted and the access_token may be used.
  • A 401 Unauthorized status code is returned after which the access_token has been revoked.

Example Request
curl "https://api.emburse.com/v1/oauth/token/challenge" -X POST -H "Authorization: Token ACCESS_TOKEN" -H "Content-Type: application/json" -d '{"answer": "WebNotes, Inc."}'
Authorization Granted
200 OK
Follow-up Questions Exist
203 Non-Authoritative Information
Access Token Revoked
401 Unauthorized
Invalid Answer
403 Forbidden

Access Tokens

Revoke Token

post /v1/oauth/token/revoke

Revoke a specific access token, or revoke all access tokens granted for a specific company. Either an access_token or a company_id must be specified.

ParameterDescription
client_id: required Your app's client_id.
client_secret: required Your app's client_secret.
access_token: optional access_token to revoke.
company_id: optional id of a company for which all access tokens should be revoked.
Example Request
curl "https://api.emburse.com/v1/oauth/token/revoke" -X POST -d "client_id=CLIENT_ID" -d "client_secret=CLIENT_SECRET" -d "access_token=ACCESS_TOKEN"
Example Response
200 OK
See it for yourself

Try our fully functioning demo account and see if Emburse is the right fit for you.