API Docs

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

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

Error Response

If the user declines your authorization request or if authorization could not be granted, the user will still be redirected back to your site; however, a code will not be provided. Instead, an error and error_description will exist as querystring parameters.

error	error_description
access_denied		The user has declined or could not grant authorization.
access_denied	No account	The user does not have an Emburse account.
access_denied	Pending approval	The user's Emburse account has not yet been approved.

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.

Parameter	Description
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.

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"

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.

Parameter	Description
grant_type: required	The value of this field should be password.
username: required	User's email address.
password: required	User's password.
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. The only scope value currently supported for this endpoint is: FinancialInformation App approval from an Emburse administrator is required before this scope value may be used.
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.

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"

201 Created
{
  "access_token": "zTF0vvvwWi...",
  "scope": []
}

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

Field	Description
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.
expires_at:	Expiration before which questions must be answered (ISO 8601 format).

curl "https://api.emburse.com/v1/oauth/token/challenge" -H "Authorization: Token ACCESS_TOKEN"

200 OK
{
  "key": "mfa.code",
  "url": "https://api.emburse.com/v1/...",
  "question": "For additional security, please submit the code that has been sent to (XXX) XXX-1234.",
  "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.

Parameter	Description
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.

curl "https://api.emburse.com/v1/oauth/token/challenge" -X POST -H "Authorization: Token ACCESS_TOKEN" -H "Content-Type: application/json" -d '{"answer": "026192"}'

200 OK

203 Non-Authoritative Information

401 Unauthorized

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.

Parameter	Description
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.

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"

200 OK