Authentication

OFX Rates API is protected by the industry standard OAuth2.0 protocol

We strongly recommend to read OAuth2.0 documentation if you are not familiar with it.

OFX OAuth Token URL:

https://sandbox.api.ofx.com/v1/oauth/token

OFX OAuth Authorise URL:

https://sandbox.api.ofx.com/v1/oauth/authorize

Supported Flows

Client credentials flow

The client credentials flow should be only used by services and applications to get an access token for their own account, outside the context of any specific user.

STEP 1: Getting access token

After registering your app, you will receive a ** ID** and a secret. TheID is considered public information, and is used to build login URLs, or included in Javascript source code on a page. The secret must be kept confidential. If a deployed app cannot keep the secret confidential, such as single-page Javascript apps or native apps, then the secret is not used, and ideally the service shouldn’t issue a secret to these types of apps in the first place. In such cases follow the Access Code grant flow.

Example request:

POST https://sandbox.api.ofx.com/v1/oauth/token 
Content-Type: application/x-www-form-urlencoded
grant_type=client_credentials&client_id=your_client_id&client_secret=your_client_secret&scope=ofxrates

or in cURL command:

curl -X POST \
  https://sandbox.api.ofx.com/v1/oauth/token \
  -H 'content-type: application/x-www-form-urlencoded' \
  -d 'grant_type=client_credentials&client_id=your_client_id&client_secret=your_client_secret&scope=ofxrates'

Example response contains temporary access token which expires in defined timeframe (seconds)

{
  "access_token": "gAAAAH_x6f2fywNe0MyI2XTh9EMj-ijVbBGQHScMPp0HWMI17kvi-jfkj348zXx3DT6c0drdDnLgMLCBsGLKUP2fDUMhIWOhK9aHfOOaRhwQsNEdAiDJRzlrBWijPhyL5prCbKqE_b-Lq9mrpHopN8TDmaUqAoY_fOmT6BcQpiOW8hAEAAIAAAACmxkA0jiLSNR4M2ko2ETrF-oG_L20KdvnQEXF9wDbR2LPPC70UqGJhQEf-K1Zw27W-M2D67-6GfwsJdzMGa9dtzSrsLl0LSLfcY_ccbFRLmPTMWA5RTq42yYKhD1U6PTyL3PQwDuStvfY3gU2_RrwQOhjlJEbFcGQCmCxHtgMj3iMegsF50PyEGbWNaxbIvO8PoNAaItrnVBNP3U-JHnrU9Eg6QB",
  "expires_in": 3599,
  "token_type": "Bearer"
}

STEP 2: Making Authenticated Requests

Once you have received the Access Token, you can use it in all subsequent API calls by setting an Authorization header.

For example to get the OFX conversion rate in-between two different currencies:

GET https://sandbox.api.ofx.com/v1/ofxrates/rates/AUD/USD/1000
Authorization: Bearer your_access_token
Content-Type: application/json

or in cURL command:

curl -X GET \
  'https://sandbox.api.ofx.com/v1/ofxrates/USD/AUD/1000' \
  -H 'authorization: Bearer your_access_token' \
  -H 'content-type: application/json'

Access Code flow

Before you can begin the Access Code process, you must first register a new app with the service. When registering a new app, you usually register basic information such as application name and a redirect URI to be used for redirecting users to for web server, browser-based, or mobile apps.

The service will only redirect users to a registered URI, which helps prevent some attacks. Any HTTP redirect URIs must be protected with TLS security, so the service will only redirect to URIs beginning with “https”. This prevents tokens from being intercepted during the authorization process. Native apps may register a redirect URI with a custom URL scheme for the application, which may look like demoapp://redirect.

STEP 1: Authorization

The first step of OAuth 2 is to get authorization from the user. For browser-based or mobile apps, this is usually accomplished by displaying an interface provided by the service to the user.

GET https://sandbox.api.ofx.com/v1/oauth/authorize?response_type=code&client_id=your_client_id&state=xyz&scope=ofxrates&redirect_uri=your_redirect_url
  • response_type - Should be ‘code’, indicates that your server expects to receive an authorization code
  • client_id - The ID you received when you first created the application
  • redirect_uri - Indicates the URI to return the user to after authorization is complete
  • scope - Should be ‘ofxrates’ for OFX Rates API
  • state - A random string generated by your application, which you’ll verify later

As a result of this command in the browser, the user will see the following screens to input the username and password and then to provide user’s consent to grant an access to user’s data.

Login dialog:

OFX Log In Dialog

and then the Consent dialog:

OFX Consent Dialog

If the user clicks “Allow,” the service redirects the user back to your site with an auth code

https://your_url.com/cb?code=AUTH_CODE_HERE&state=1234zyx
  • code - The server returns the authorization code in the query string
  • state - The server returns the same state value that you passed

STEP 2: Token exchange

Your server exchanges the auth code for an access token:

POST https://sandbox.api.ofx.com/v1/oauth/token 
Content-Type: application/x-www-form-urlencoded
grant_type=authorization_code&client_id=your_client_id&client_secret=your_client_secret&code=your_auth_code&redirect_uri=your_redirect_url&scope=ofxrates

or in cURL command:

curl -X POST \
  https://sandbox.api.ofx.com/v1/oauth/token \
  -H 'content-type: application/x-www-form-urlencoded' \
  -d 'grant_type=authorization_code&client_id=your_client_id&code=your_auth_code&redirect_uri=your_redirect_url&client_secret=your_client_secret&&scope=ofxrates'
  • grant_type=authorization_code - The grant type for this flow is authorization_code
  • code=AUTH_CODE_HERE - This is the code you received in the query string
  • redirect_uri=REDIRECT_URI - Must be identical to the redirect URI provided in the original link
  • client_id=CLIENT_ID - The id you received when you first created the application
  • client_secret=CLIENT_SECRET - The secret key you received when you first created the application
  • scope - Should be ‘ofxrates’ for OFX Rates API

Example response contains temporary access token which expires in defined timeframe (seconds), along with a ‘refresh_token’, that lives much longer.

{
   "access_token": "Q0NEficYFme0pexJvCq0B1m1b5GM",
   "expires_in": 3599,
   "token_type": "Bearer",
   "refresh_token": "4S9dpU3HzEzrAA6AWH2dWxepYxmPfoUG"
}

Using Refresh Token

When an access token expires, a new access token can be generated using the ‘Refresh Token’ grant type.

This allows clients to continue to have a valid access token without further interaction (re-authentication) with the user.

Note: To get a new access token, always use the refresh token returned in the most recent response.

A Refresh token expires in 2592000 seconds (30 days).

Request

POST https://sandbox.api.ofx.com/v1/oauth/token 
Content-Type: application/x-www-form-urlencoded
        grant_type=refresh_token&client_id=your_client_id&client_secret=your_client_secret&scope=ofxrates&refresh_token=your_latest_refresh_token

or in cURL command:

curl -X POST \
  https://sandbox.api.ofx.com/v1/oauth/token \
  -H 'content-type: application/x-www-form-urlencoded' \
  -d 'grant_type=refresh_token&client_id=your_client_id&client_secret=your_client_secret&scope=ofxrates&refresh_token=your_latest_refresh_token'
  • grant_type=refresh_token - The grant type for this flow is ‘refresh_token’
  • refresh_token=REFRESH_TOKEN_HERE - This is the refresh token you received previously

The response to the refresh token grant is the same as when issuing an access token.

STEP 3: Making Authenticated Requests

Once you have received the Access Token, you can use it in all API calls that require you to be authorized by providing Authorization header parameter.

For example to get the OFX conversion rate in-between two different currencies:

GET https://sandbox.api.ofx.com/v1/ofxrates/USD/AUD/1000
Authorization: Bearer your_access_token
Content-Type: application/json

or in cURL command:

curl -X GET \
  'https://sandbox.api.ofx.com/v1/ofxrates/USD/AUD/1000' \
  -H 'authorization: Bearer your_access_token' \
  -H 'content-type: application/json'