OAuth2 Authentication

OAuth2 is the preferred method of authenticating access to the API. OAuth2 allows authorization without the external application getting the user's email address or password. Instead, the external application gets a token that authorizes access to the user's account. The user can revoke the token for one application without affecting access by any other application.

Authentication options

All Aha! API keys are tied to a specific user and account in accordance with security best practices. This ensures that every action taken inside Aha! is traceable to a specific user. We do not currently offer authentication outside the context of specific users.

Application authentication can be achieved in multiple ways depending on your architecture:

Option 1: Use an existing Aha! user account API key. All actions taken by your application will be attributed to this user.
Option 2: Create an Aha! user specifically for your application API access and assign it appropriate permissions and manage its API keys. This would just be another user in your Aha! account but you can use it like a "service account."
Option 3: Create an OAuth2 application in your Aha! account and then implement the OAuth2 flow in your application. Each user of your application would have to be a valid Aha! user and they would be required to authorize the application. Each user that uses/authorizes the application would get redirected to your application with an OAuth2 token for each individual user that could be used to call the Aha! API on behalf of that user.

Register an application

An external application must be registered with Aha! before it can use OAuth2 to authenticate users.

A registered application can be used by all users of Aha!, not just the users of the account of the person registering the application. However, registered applications are not discoverable—simply registering your application does not make it visible to any other Aha! users (even users in your own account)—it is up to you to publicize your application.

Register your application

Once an application is registered you can use the client ID,client secret and redirect URL in the authorization flow.

Authorization flow

To authorize an external application to authenticate as a user, the application uses browser redirects to send the user to Aha!. Aha! supports the OAuth2 authorization code flow (suitable for server based applications), and implicit grant flow (suitable for browser based applications).

Redirect user to request access

The user should be redirected in their browser to the OAuth2 authorize URL, passing the application specific parameters:

GET https://<subdomain>.aha.io/oauth/authorize

Name	Description
`client_id` `*`	Required. The client ID created when the application was registered.
`redirect_uri` `*`	Required. The URL where the user will be redirected after they have authorized the application. This must be the same as the redirect URL provided when the application was registered.
`response_type` `*`	Required. Controls which flow will be used to return the `access_token`. Using a value of `code` will use the authorization code flow and using a value of `token` will use the implicit grant flow.

Aha! redirects user back to application

Once the user authorizes the application their browser will be redirected back to the redirect_uri.

If the implicit grant flow is being used then the URL the user is redirected to will include a parameter named access_token which is the value of the access token that can be directly used with the API.

If the authorization code flow is being used then Aha! will include a parameter in the URL named code which must be exchanged for the access token by making another request to Aha! in the next step.

This redirect will also include a account_subdomain parameter. If the user was sent to secure.aha.io at the start of the flow, this parameter contains the subdomain of that user's account. You can use this subdomain for the request access token flow below, or for making API requests

Request access token

The application exchanges the code from the previous step for an access token. In this step the application uses its secret which provides an additional level of security since Aha! can be sure that it is an authorized application that is making the request on behalf of the user.

POST https://<subdomain>.aha.io/oauth/token

Parameters

Name	Description
`code` `*`	Required. The code value that was returned by the previous step in the flow.
`client_id` `*`	Required. The client ID created when the application was registered.
`client_secret` `*`	Required. The client secret that was created when the application was registered.
`grant_type` `*`	Required. Must contain the value `authorization_code`.
`redirect_uri` `*`	Required. This must be the same as the redirect URL provided when the application was registered.

For example:

curl "https://mydomain.aha.io/oauth/token" -X POST --data "client_id=a73bbb264c7432421b9abc05fae6bf9379b9fb49bbefdf84ab036487fd5b&client_secret=467b9a301fedac887a46a23d3f29d76afdff30ac9bbf6c8c&code=10dbffca01ce6985868b4cee84e0444f5bcdda104b60a13038c1d74b72e6797f&grant_type=authorization_code&redirect_uri=http://lvh.me/app_callback.html"

The response to this POST will be a JSON string containing the access token that can then be used to access the API:


{
  "access_token":"1d08ddc8c781ca1afd75ffb0870aa445e2a56ee30ba123ff95f90cf8a270bec2",
  "token_type":"bearer"
}