OAuth2

OAuth2 authentication work-flows require a Client ID and secret in order to be used. For more information on obtaining and working with an OAuth2 client, see: Managing OAuth Clients

Obtaining an Access Token

Authorization can be accomplished using the grant_types: password or authorization_code.

Password Type Work-flow

The password grant_type method allows you to obtain an access token by providing the end-user with a login form that captures the username and password credentials and then transmits them to OmniFund for authorization. This is useful for applications that do not have the ability to provide a URL end-point to capture a response redirect of the user's browser. If this ability is possible, our suggestion would be to use the authorization_code type work-flow.

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://secure.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"
}

Authorization Code Type Work-flow

The ideal work-flow when working with user authentication. This work-flow allows the user to enter their credentials and authenticate on forms hosted by OmniFund. Once a user has successfully validated their credentials and approved the application to access their account, the user's browser is redirected to a URL provided at the time the request is made. An authorization code sent back along with this redirect so that it can be captured by the integration and used to generate an access and refresh token set for the user.

Create a new OAuth Client (see: Managing OAuth Clients). Once the new client has been created, you will need to edit the client and update the following:
- Client Name - Give the client a descriptive name to describe the application.
  
  The Client Name will be displayed to the user when they are prompted to allow/deny access for the authorization request
- Allowed Redirect URI - Add in a redirect URI that will be used to capture the authentication code. More than one URI can be entered. These will be used to validate the URI provided when the authentication request is initiated.
Forward user to the URL: https://secure.gotobilling.com/oauth/v2/auth?client_id=CLIENT_ID&response_type=code&redirect_uri=ALLOWED_REDIRECT_URI. Note: replace CLIENT_ID with your Client ID, and ALLOWED_REDIRECT_URI with one you configured in the previous step.

Based on our example above, we would send the user to the following URL:
https://secure.gotobilling.com/oauth/v2/auth?client_id=3_63mzt9x8bgkksssosgk8wccskwk0g0o88s88swgwgcww4swkck&response_type=code&redirect_uri=https://my.domain.com/redirect_url
The user will be presented with the OmniFund login screen. Once they have authenticated using their username and password, they will be asked to Allow or Deny the request by your application
After selecting Allow/Deny, user will be redirected to the redirect_uri specified in the initial request. The "code" GET parameter will be included.

In this example our user would be redirect to the following URL:
https://my.domain.com/redirect_url?state=&code=YzFiMGQ3NzZkYmNlMzAyZGI3Y2IwZDkzMDhlOWFiYjAyYzNlOGRk3YzBkODliMmRhYmVlZjkxMmE2ZDdjMQ

Once you have obtained the code value from the response GET parameter, you will need to initiate the access token request from within your application. And provide the following:

client_id & client_secret: OAuth2 client credentials that were generated above
code - The authorization code obtained from the successful redirect
redirect_uri - The URI matching the one used in the initial authentication request.
grant_type: Should be set to "authorization_code"

Access token request example

$ http POST https://secure.gotobilling.com/oauth/v2/token \
    grant_type=authorization_code \
    client_id=3_63mzt9x8bgkksssosgk8wccskwk0g0o88s88swgwgcww4swkck \
    client_secret=4ok2x70rlfokc8g0wws8c8kwcokw80k44sw0so0k \
    code=YzFiMGQ3NzZkYmNlMzAyZGI3Y2IwZDkzMDhlOWFiYjAyYzNlOGRk3YzBkODliMmRhYmVlZjkxMmE2ZDdjMQ \
    redirect_uri=https://my.domain.com/redirect_url
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"
}

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". OAuth2 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://secure.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"
}