Authentication

The Akiles API uses the standard RFC-6479 OAuth 2.0 protocol for authentication.

OAuth allows your app to interactively request access to customers’ Akiles organizations and obtain access tokens for them. This makes the experience smoother and more secure, since the customer doesn’t have to manually copy and paste a sensitive API key.

This section is not intended to be a full explanation on how OAuth works, just a quick reference to get started. For more info, consult online documentation about OAuth.

Client ID and Client Secret

Your OAuth application needs a Client ID and a Client Secret to operate.

• The Client ID is considered public, it is OK to expose it to front-ends (and is in fact necessary to do so).
• The Client Secret must be maintained confidential since it is used to obtain access tokens. Always use it from your server, never send it or expose it to your frontend.

To obtain your application’s Client ID and Secret, create an application in the Developer Center.

Token types

• Access token: used to make API calls, expires 1 hour after issuance.
• Refresh token: used to obtain new access tokens when they expire.

Authorization flow

1. Generate a cryptographically-secure random string state and store it somewhere you can access it later (e.g. a cookie)
2. Start the flow by redirecting the user to the following URL:

https://auth.akiles.app/oauth2/auth?client_id=CLIENT_ID_HERE>&redirect_uri=https://your-app.example.com/redirect&response_type=code&scope=full_read_write offline&state=STATE_HERE

3. The Akiles authorization server will prompt the user to choose a user account and organization.
4. The Akiles authorization server will ask the user to authorize your requested scopes.
5. The user gets redirected to your redirect_uri:

https://your-app.example.com/redirect?code=CODE_HERE&scope=full_read_write offline&state=STATE_HERE

6. Check the state you have received matches the original state you stored. If it doesn’t, abort. This is necessary to protect against CSRF / session poisoning attacks.
7. Exchange the authorization code for the access and refresh tokens.

POST https://auth.akiles.app/oauth2/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
client_id=CLIENT_ID_HERE
client_secret=CLIENT_SECRET_HERE
code=CODE_HERE

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

{
    "access_token": "ACCESS_TOKEN_HERE",
    "expires_in": 3599,
    "refresh_token": "REFRESH_TOKEN_HERE",
    "scope": "full_read_write offline",
    "token_type": "bearer"
}

8. You’re done! Save the access token and refresh token.

You can now use the access token to make API calls on behalf of the user’s organization. Just include an Authorization: Bearer header with the access token:

GET https://api.akiles.app/v2/organization
Authorization: Bearer ACCESS_TOKEN_HERE

The access token expires in 1 hour. You can obtain new access tokens with the refresh token.

Refresh token flow

POST https://auth.akiles.app/oauth2/token
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token
client_id=CLIENT_ID_HERE
client_secret=CLIENT_SECRET_HERE
refresh_token=REFRESH_TOKEN_HERE

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

{
    "access_token": "NEW_ACCESS_TOKEN_HERE",
    "expires_in": 3599,
    "refresh_token": "NEW_REFRESH_TOKEN_HERE",
    "scope": "full_read_write offline",
    "token_type": "bearer"
}

Store both the new access and refresh tokens. The old refresh token, once used, is no longer guaranteed to keep working forever.

Scopes

• full_read_write: read-write access to all the objects. Same as an administrator user.
• full_read_only: read-only access to all the objects.
• offline: allows offline access. You need this to obtain refresh tokens.

Troubleshooting

I’m not getting any refresh token, only the access token

Make sure you’ve requested the offline scope when initiating the authorization flow.