Authentication

Retrieving an Access Token

You can invoke the permissions dialog by constructing a URL using your client_id and necessary scopes. Note that the URL endpoint here is different from the API endpoint. You can learn more about available scopes at the URL below.

https://sys.akia.com/oauth/authorize?client_id=<CLIENT_ID> &scope=<SCOPE_1>,<SCOPE_2>&response_type=code

Upon authorization, Akia will redirect to your redirect_uri with a code parameter in the query string. It will look something like the URL below. Note that a valid redirect_uri must use HTTPS and must not contain a fragment (#).

https://<REDIRECT_URI>/?code=<AUTHORIZATION_CODE>

You will use this authorization code to request an access token with your client_id and client_secret. This authorization code may only be used once and expires after 10 minutes.

curl -X POST \ -d "code=<AUTHORIZATION_CODE>" \ -d "grant_type=authorization_code" \ -d "client_id=<CLIENT_ID>" \ -d "client_secret=<CLIENT_SECRET>" \ "https://api.akia.com/oauth/token" { "token_type": "bearer", "refresh_token": "<REFRESH_TOKEN>", "expires_in": 86400, "access_token": "<ACCESS_TOKEN>" }

This will return a response with the following payload with an access token, refresh token, and expiration time. All access tokens expire in 24 hours. Once expired, you can use the refresh token to generate a new one.

Redirect URI

You can optionally set a redirect_uri parameter to have the code passed to another URL of your choosing. This is good while testing or for use when your implementation does not have a static URL. Simply invoke the authentication dialog with the redirect_uri parameter.

https://sys.akia.com/oauth/authorize?client_id=<CLIENT_ID> &scope=<SCOPE_1>,<SCOPE_2>&response_type=code &redirect_uri=<REDIRECT_URI>

When using this parameter, fetching the token then requires that the redirect_uri parameter is also provided. It MUST match the redirect_uri that was provided when fetching an authorization code.

curl -X POST \ -d "code=<AUTHORIZATION_CODE>" \ -d "grant_type=authorization_code" \ -d "client_id=<CLIENT_ID>" \ -d "client_secret=<CLIENT_SECRET>" \ -d "redirect_uri=<REDIRECT_URI>" \ "https://api.akia.com/oauth/token"

Refreshing Access Tokens

Even though it can be done, you should not refresh the token on every call. This API call is very expensive and will cause your system to be rate limited quickly.

curl -X POST \ -d "refresh_token=<REFRESH_TOKEN>" \ -d "grant_type=refresh_token" \ -d "client_id=<CLIENT_ID>" \ -d "client_secret=<CLIENT_SECRET>" \ "https://api.akia.com/oauth/token"

This API call returns the same response as the above, including a new refresh token. Once you use the refresh token, it expires along with the previous access token.