2. Authorize third party

The end user must give the consent for third party application to use their data. So third party application must drive the initial process to get user consent and authorization.

OFX GCA 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 use access code flow in identity server to initiate the initial authorization process with third party application and end user.

Access Code flow

Before you can begin the Access Code process, you must first wait till you get an application created by OFX team with the service.

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=gca-aisp&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 ‘gca-aisp’ for OFX GCA 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

  • 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

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=gca-aisp'
  • 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 ‘gca-aisp’ for OFX GCA 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).


POST https://sandbox.api.ofx.com/v1/oauth/token 
Content-Type: application/x-www-form-urlencoded

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=gca-aisp&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 retrieve the list of user beneficiaries:

GET https://sandbox.api.ofx.com/v1/gca/virtual-accounts
Authorization: Bearer your_access_token
Content-Type: application/json

or in cURL command:

curl -X GET \
  'https://sandbox.api.ofx.com/v1/gca/virtual-accounts' \
  -H 'authorization: Bearer your_access_token' \
  -H 'content-type: application/json'