Documentation

Everything you need to know about using Chip's OAuth API.

This API is read-only and is limited to customer account balances, goals and goal progress, and basic identity information. We may have plans to expand that in future, so the scope of your tokens may change at a later date.

To start, just register for an account using ‘register’ above and then add a new client. All clients will be test clients until approved by Chip. While in test mode, you’ll be able to generate test users.

For test users, all pin codes will be sent to the mobile number of the user who created the client, if you need to change this, or have issues contact alan@getchip.uk

URL https://api.getchip.tech/
Version v1.0
Last Update Saturday 2nd May 2019

Once approved you may force sandbox use by appending sandbox with a truthy value (1 or true) to any request.

 

Authentication

We use standard OAuth for authentication. You'll send a request to us, then we'll authorise this and return you a code, you can then use this code to request a token. This token may be be stored and used to make requests.

These tokens will expire every 24 hours, but you can issue a new request on our refresh endpoint and we'll issue you a new token.

Authorization Code

The first step is to redirect the user to us for us to authenticate. You should include the following in your request.

Parameter Description
client_id
The client_id you created in the API console.
redirect_uri
This value must match one of the values added to your client in the API console.
state
This should be a unique random value decided by you and send by your request, this will be valued in later requests.

Example

curl GET https://api.getchip.tech/oauth? client_id=nh3633ty23f2h32g23u63 &redirect_uri=https://example.net/callback &state=h63h3373ii2i3h2k3n23jj2g3jg3n23m2b3n2v3

Once validated, a user will be redirected to the redirect_uri you provided, along with the query parameter code and the state value you sent us.

Access Token

Now you have an a code you can exchange this for an access_token which you will use with our APIs. Your requests should contain the following.

Parameter Description
client_id
The client_id you created in the API console.
client_secret
The client_secret from the API console.
code
The code we returned to you in the first step.
state
The state you sent us in your first request.
redirect_uri
This value must match the same redirect_uri you sent in the first request.
grant_type
This must be set to authorization_code.

Example

curl GET https://api.getchip.tech/oauth/token? client_id=nh3633ty23f2h32g23u63 &client_secret=vvafrw42rw6wytw523geheu73hjbt56363g3g37833h3hge &redirect_uri=https://example.net/callback &state=h63h3373ii2i3h2k3n23jj2g3jg3n23m2b3n2v 3&grand_type=authorization_code &code=76474uhj23g4hjf412423941243yu2jkh4j2134io2iy3u4gkj2b4m

If everything is okay you'll be returned an access token.

Response

{ "access_token": "2ee82ccec6476a62e7397d2ab8f85a41c6754fd51cd529b2d12930b0ea0737db5504e2c08a77ec64e2cdaba0e0b0a3713b3f1e4c42c5a22b747a8b4d959993d5" "refresh_token": "293bc2f7553a76462331999582b6b2b2dc6c97d7d0a51185195e43d86e6d7958e0655676ec617ab5ca9c56196c389f5839e58a76ed31b4e67a7f298aafd1d6dd" "expires_in": 36000 "scope": "*" }

Refresh Token

A refresh token is exactly the same as an access token, except your grant_type should be set to refresh_token, and you should request the /oauth/refresh endpoint instead of /oauth/token.

You may send the request to the `/oauth/token` enpoint if you wish.

You may omit the state and request_uri if you wish

If an expired token is used on an endpoint, the API will return 419 HTTP Code to tell you it’s safe to request a refresh token.

 

API

Once you have a token you can make requests against our api. The access_token from your token response should be sent as a get parameter called access_code on all API requests.

User Information

The /api/me endpoint can be used to return all information for a given oauth token.

Example

curl GET https://api.getchip.tech/me/?access_token=2ee82ccec6476a62e7397d2ab8f85a41c6754fd51cd529b2d12930b0ea0737db5504e2c08a77ec64e2cdaba0e0b0a3713b3f1e4c42c5a22b747a8b4d959993d5

Response

{ "first_name": "Alan", "last_name": "Cole", "email_address": "alan@getchip.uk", "phone_number": "0712345678", "currency": "GBP", "balances": { "pending_balance": 45.12, "savings_balance": 456.00, "average_save": 42.00 }, "goals": [ { "id": 1232, "name": "Wedding", "end_date": "12-12-12 12:12:12+01", "balance": "10000", "goal_amount": "5000" }, { "id": 1324, "name": "House", "end_date": "12-12-12 12:12:12+01", "balance": "25600", "goal_amount": "25000" } ] }

Note: This data format may change over time, high traffic users will be notified before values change.

 

Error Codes

Our API error codes and what they mean.

Some errors will return a JSON body containing further explanation, most will only return the code.

Healthy responses will return a 200 code.

If a user is redirected to us and fails to login, or leaves the process before finishing, you will not be notified.

Code Description
404 You requested a resources that we couldn't identify.
401 Something went wrong during login, most likely your client_id or client_secret were wrong, we'll also return this code if the redirect_uri doesn't match our records or if your state value changes at any stage of the request.
419 We return a 419 code when an access_token has expired and you may try and gain a new token using the associated refresh_token
500 If you see a 500, email us as it means its most likely an us API error.