Authorizing With Oauth2

Learn how to gain permission to access a user's data

πŸ“˜

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 obtain enduring access to a user's data.

Need a hand? Join our Slack Channel for in-person help.

Prerequisites

Before we begin, you will need:

  • Your Akahu App ID Token.
  • Your Akahu App Secret.
  • Your Akahu app's Redirect URIs (you must supply at least one of these when you register an Akahu app).

The first two 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://oauth.akahu.io, with several query parameters set.

ParameterExampleDescription
response_typecodeThe type of oauth response. Currently "code" is the only supported option.
client_idapp_token_111111111111111111111111Your App ID Token.
email[email protected](Optional) The user's email.
connectionconn_1234(Optional) Direct the user to a specific connection from your app
redirect_urihttps://example.com/auth/akahuWhere to redirect the user once they have accepted or rejected the access request. This must match one of your app's Redirect URIs.
scopeENDURING_CONSENTThe type of oauth flow to perform. ENDURING_CONSENT is all you need to supply here.
state1234567890(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://oauth.akahu.io?
  response_type=code&
  client_id=<<appToken>>&
  email=user%40example.com&
  redirect_uri=https%3A%2F%2Fexample.com%2Fauth%2Fakahu&
  scope=ENDURING_CONSENT&
  state=1234567890

πŸ‘

By default, you only need to supply Akahu with the scope for the type of OAuth request you wish to perform. Akahu will automatically add all of the additional scopes that your app is allowed to access. If you wish to only request a subset of your app's available scopes, simply set the scope parameter to a space-separated list of the scopes you desire.

The Authorization Response

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

A Successful Response

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

ParameterExampleDescription
codec5bae672...88a33f1fAn Authorization Code. Keep track of this for the next step.
state1234567890The state you supplied when you made the request.
sourceoauthFor OAuth requests, this will always be "oauth".
eventACCEPTThe type of event the user has performed. One of ACCEPT, REVOKE, UPDATE.

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 may be a JSON string or url encoded form data, with the following keys:

KeyExampleDescription
grant_typeauthorization_codeGrant type. Only "authorization_code" is currently supported.
codeid_1234512345123451234512345The Authorization Code you received earlier.
redirect_urihttps://example.com/auth/akahuThe Redirect URI you originally supplied, for verification purposes.
client_idapp_token_111111111111111111111111Your App ID Token.
client_secret1a785560...c1ae44c4Your App Secret

A Successful Response

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

KeyExampleDescription
successtrueIndicates that the operation was successful.
access_token"user_token_111111111111111111111111"A User API Token.
token_type"bearer"Will always be "bearer".
expires_in31535999Time until the User API Token expires.
scope"IDENTITY_EMAILS ACCOUNTS ENDURING_CONSENT"The scopes 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 allowed by the permissions you requested.

Simply set the Authorization header to Bearer {User API Token} and the X-Akahu-ID header to {App ID Token} and make a request - a good starting point is the /me endpoint, which gives you basic details of the user who authorized you along with the expiry date of your token.

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


Did this page help you?