Authorization

Getting an access token

Getting an access token for your own account

In order to use the API, you first need to make sure you can obtain access tokens. At this moment, Aikido's API only supports OAuth 2.0's Client Credentials grant for getting access tokens.

DISCLAIMER The Client Credentials flow is meant for server to server communication only. Do not share the client secret with users.

In order to obtain an access token, your Aikido workspace admin first must create client credentials via the integrations page in Aikido. This will result in a client ID and client secret which can be used to obtain an access token.

To obtain an access token you must make a POST request to https://app.aikido.dev/api/oauth/token with grant_type: client_credentials which is detailed here in the reference.

For the Client Credentials flow, you must supply the Client ID and Client Secret you obtained in the integration page via a basic authorization header. The Basic authorization header requires you to supply a username (Client ID) and password (Client Secret) in a Base64 encoded string, separated with a colon.

Getting an access token for a 3rd party account via Oauth2

If you want to integrate your own software with Aikido and provide this integration to your users, you can use the OAuth2 Authorization Code flow. This flow is meant for 3rd party integrations and allows users to grant your application access to their Aikido workspace.

To use the OAuth2 Authorization Code flow, you must first create client credentials via the integrations page in Aikido. Make sure to select 'Public' as App Type and fill in a Redirect URI. This will result in a client ID and client secret which can later be used to obtain a refresh token.

Redirect your users to https://app.aikido.dev/oauth/authorize?client_id=AIK_CLIENT_...&state=xy where client_id is the client ID you obtained in the integration page. The user will be asked to log in and grant your application access to their workspace. After the user has granted access, they will be redirected to the Redirect URI you specified in the integration page with a code parameter.

You can now exchange this code for a refresh token by making a POST request to https://app.aikido.dev/api/oauth/token with grant_type: authorization_code and the code you obtained in the previous step, which is detailed here in the reference. You must supply the Client ID and Client Secret you obtained in the integration page via a basic authorization header. The Basic authorization header requires you to supply a username (Client ID) and password (Client Secret) in a Base64 encoded string, separated with a colon.

Your app can now be used to connect to your own account. To be able to connect to 3rd party account, your app needs to be verified. Contact us via chat or [email protected].

Using the access token

After you have obtained an access token, you can use it to authenticate your requests to the API. You must supply the access token in the Authorization header of your requests. The access token must be prefixed with Bearer and separated with a space. For example: Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c.

Refreshing the access token

Access tokens have a limited lifetime. When an access token expires, you must obtain a new access token using the refresh token you obtained when you first obtained the access token. To refresh an access token, you must make a POST request to https://app.aikido.dev/api/oauth/token with grant_type: refresh_token and the refresh token you obtained when you first obtained the access token, which is detailed here in the reference. You must supply the Client ID and Client Secret you obtained in the integration page via a basic authorization header. The Basic authorization header requires you to supply a username (Client ID) and password (Client Secret) in a Base64 encoded string, separated with a colon.