Generating an OAuth Client

To generate a new set of OAuth Client credentials simply log into the OmniFund portal and navigate to Profile >> API Access. Then click on the "New OAuth Client" button. A new Client ID and Secret will be generated and displayed.

NOTE: While the Client ID can be viewed from the API Access section at any time, the Client Secret will only be view-able when it is created and is non-recoverable. Please ensure that you securely store your Client secret to protect against theft or loss. If you happen to lose or forget the client secret, a new client will need to be create and your integration credentials updated.

To make managing and identifying multiple integration points easier, OAuth clients can be assigned a descriptive name. To update the name of the client simply choose the edit action and fill in the desired value.

Obtaining an Access Token

To obtain an access token for a user, you will need to perform a HTTP POST to the token end-point. With the request you will need to include the following parameters:

"client_id" and "client_secret". OAuth client credentials that were generated above
"username" and "password". These represent the credentials for the user requesting the access token.
"grant_type". This should be set to "password"

Upon a successful request, you will receive a JSON formatted response with the following fields:

access_token
expires_in
refresh_token
scope
token_type

Access token request example

$ http POST https://sandbox.gotobilling.com/oauth/v2/token \
    grant_type=password \
    client_id=1_3bcbxd9e24g0gk4swg0kwgcwg4o8k8g4g888kwc44gcc0gwwk4 \
    client_secret=4ok2x70rlfokc8g0wws8c8kwcokw80k44sg48goc0ok4w0so0k \
    username=omnifund_user \
    password=omnifund_password
HTTP/1.1 200 OK
Cache-Control: no-store, private
Connection: close
Content-Type: application/json
...
{
    "access_token": "MDFjZGI1MTg4MTk3YmEwOWJmMzA4NmRiMTgxNTM0ZDc1MGI3NDgzYjIwNmI3NGQ0NGE0YTQ5YTVhNmNlNDZhZQ",
    "expires_in": 3600,
    "refresh_token": "ZjYyOWY5Yzg3MTg0MDU4NWJhYzIwZWI4MDQzZTg4NWJjYzEyNzAwODUwYmQ4NjlhMDE3OGY4ZDk4N2U5OGU2Ng",
    "scope": null,
    "token_type": "bearer"
}

Refreshing an Access Token

Similar to the initial "password" access token request, a refresh token request substitutes the username/password credential fields for the refresh_token field. Upon a successful request, a new access and refresh token will be generated. Request fields:

"client_id" and "client_secret". OAuth client credentials that were generated above
"refresh_token". Refresh token value obtained in an earlier request.
"grant_type". This should be set to "refresh_token"

Refresh token request example

$ http POST https://sandbox.gotobilling.com/oauth/v2/token \
    grant_type=refresh_token\
    client_id=1_3bcbxd9e24g0gk4swg0kwgcwg4o8k8g4g888kwc44gcc0gwwk4 \
    client_secret=4ok2x70rlfokc8g0wws8c8kwcokw80k44sg48goc0ok4w0so0k \
    refresh_token=ZjYyOWY5Yzg3MTg0MDU4NWJhYzIwZWI4MDQzZTg4NWJjYzEyNzAwODUwYmQ4NjlhMDE3OGY4ZDk4N2U5OGU2Ng
HTTP/1.1 200 OK
Cache-Control: no-store, private
Connection: close
Content-Type: application/json
...
{
    "access_token": "Mjk0MDQ5MzUyNzA5YjgwYmE0MzhkM2I5NzRmOTJkMWE3Njk5N2Y0ZTAxNTdkNjQwY2Y0YmZhZmJhNjc3NTQ5ZA",
    "expires_in": 3600,
    "refresh_token": "ZjFmNTZjZmQ3NDEyZjdhZDdiOWY2MWZmOGFjOTkyMGVhNmNlYWFkYmE4ZWI0OGI5YjkwNzQyY2NlN2MwMDJkNA",
    "scope": null,
    "token_type": "bearer"
}

Token Login

To allow the user to login to the OmniFund application with an access token, it will need to be included in the "Authorization" header of a POST request to the login end-point.

Access token login example

$ http POST https://sandbox.gotobilling.com/login \
    "Authorization:Bearer MDFjZGI1MTg4MTk3YmEwOWJmMzA4NmRiMTgxNTM0ZDc1MGI3NDgzYjIwNmI3NGQ0NGE0YTQ5YTVhNmNlNDZhZQ"
HTTP/1.1 200 OK

Browser not supported