Managing OAuth Clients

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

$ 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"

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

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