Authorizing With OAuth2

This guide is not applicable to Personal Apps as they are authorized when they are created. See our Getting Started Guide to set up your Personal App.

Akahu supports a standard OAuth2 authorization flow, after which your app will be able to access a user's data.

Prerequisites

Before we begin, you will need:

  • Your Akahu App ID Token.
  • Your Akahu App Secret.
  • Your Akahu app's Redirect URI.
  • The user's Email Address.

The first three will be given to you when you register an app with Akahu.

Make sure you keep your App Secret private! Never include it in any frontend or user-accessible source code. We recommend you use environment variables to store the secret.

The Authorization Request

To begin the OAuth flow, the user must be directed to https://my.akahu.io/oauth, with several query parameters set.

Parameter Example Description
response_type code The type of oauth response. Currently "code" is the only supported option.
client_id app_token_1111111111111111111111111 Your App ID Token.
email foo@bar.com The user's email.
redirect_uri https://example.com/auth/akahu Where to redirect the user once they have accepted or rejected the authorization. This must match your app's Redirect URI.
scope IDENTITY_BASIC ACCOUNTS Space-separated permissions that your app is requesting access to.
state 1234567890 (Recommended) An arbitrary string that will be returned with the Authorization Code. Useful to keep track of request-specific state and to prevent CSRF attacks.

Here is an example uri using the values above, with newlines included for readability:

https://my.akahu.io/oauth?
  response_type=code&
  client_id=app_token_1111111111111111111111111&
  email=user%40example.com&
  redirect_uri=https%3A%2F%2Fexample.com%2Fauth%2Fakahu
  &scope=IDENTITY_BASIC+ACCOUNTS
  &state=1234567890

The Authorization Response

The authorization response is delivered to your app by redirecting the user to your app's Redirect URI, with results included in the query parameters.

A Successful Response

Once the user accepts your app's request for authorization, they will be returned to your Redirect URI with the following query parameters:

Parameter Example Description
code c5bae672...88a33f1f An Authorization Code. Keep track of this for the next step.
state 1234567890 The state you supplied when you made the request.
source oauth For OAuth requests, this will always be "oauth".

An Error Response

Two types of errors can be returned:

  • An access denied error. The user has declined to give your app access to the permissions it has requested.
  • A configuration error. There was something wrong with your authorization request.

Details are supplied by the error and error_description (optional) query parameters.

The error codes given are standard for OAuth implementations, for more details see this document.

Exchanging the Authorization Code

In order to get a User API Token you must exchange your Authorization Code by making a POST request to the /token endpoint (Reference). This must be done within 60 seconds of receiving the Authorization Code.

The body must be JSON, with the following keys:

Key Example Description
grant_type authorization_code Grant type. Only "authorization_code" is currently supported.
code c5bae672...88a33f1f The Authorization Code you received earlier.
redirect_uri https://example.com/auth/akahu Your app's Redirect URI, for verification purposes.
client_id app_token_1111111111111111111111111 Your App ID Token.
client_secret 1a785560...c1ae44c4 Your App Secret

A Successful Response

If all parameters are correct you will receive a JSON response body with the following keys:

Key Example Description
success true Indicates that the operation was successful.
access_token "user_token_1111111111111111111111111" A User API Token.
token_type "bearer" Will always be "bearer".
expires_in 86400 Time until the User API Token expires.
scope "IDENTITY_BASIC ACCOUNTS" The permissions granted by this User API Token, separated by spaces.

An Error Response

If the response success key is false, details are supplied by the error and error_description (optional) keys.

For more information on the error codes returned, see for more details see this document.

Next Steps

Now that you have a User API Token, you can access those endpoints consistent with the permissions you requested.

Simply set your Authorization header to Bearer {User API Token} and make a request - a good starting point is the /me endpoint, which gives you details of the user who authorized you along with details of when your token will expire.

Well done! Now view our Full API Documentation or our Quick Start Guides and start building!