Copy page

Basics

Authentication

The Aerion API uses OAuth 2.0 with the password grant type. As part of the token request, users must identify which Aerion tenant they are via the origin or companyurl headers. After successful authentication, API feeds can be accessed with Bearer authentication.

SSO and other grant types are not currently supported by the Aerion API. A refresh token issued by a web-based SSO login can be used to seed an API integration, however we do not currently support authorization-code grant types for SSO or Password login login for use with the API.

Password Authentication

The following fields should be sent, form encoded, to the oauth2/token endpoint:

• grant_type: password
• username: {your email address}
• password: {your password}
• client_id: {an arbitrary string describing your app}
• client_secret: {an arbitrary string}

The client_id and client_secret values do not need to be registered and are not validated for normal API usage, however they must be present. We recommend using a client_id that identified your app. The fields are reserved for future non-password / non-user-account related authentication methods.

Either the origin, referrer, or companyurl headers must be present to identify the target account. API access can optionally be directed at the neutral api.aerion.app address rather than a company-specific domain, but the header must identify the target account.

Here are two example requests, for cURL and JavaScript Fetch. Items in {brackets} should be replaced with your appropriate values.

cUrl

Code
curl 'https://{your-domain}.aerion.app/oauth2/token' \
  -H 'content-type: application/x-www-form-urlencoded' \
  -H 'origin: https://{your-domain}.aerion.app' 
  --data-raw 'grant_type=password&username={your-username}&password={your-passowrd}&client_id={your-app-name}&client_secret={must-be-present}'

JavaScript / Node.js Fetch

Code
fetch("https://{your-domain}.aerion.app/oauth2/token", {
  "headers": {
    "content-type": "application/x-www-form-urlencoded",
    "companyurl": "{your-domain}.aerion.app",
  }, 
  "body": "grant_type=password&username={your-username}&password={your-passowrd}&client_id={your-app-name}&client_secret={must-be-present}",
  "method": "POST",
});

Response

The standard OAuth 2.0 response in JSON format includes the access token, refresh time, and expire time (in seconds — usually 1 hour / 3600 seconds).

Code
{
    "access_token": "0001112223334445556667778899aabbccddeeff",
    "token_type": "Bearer",
    "expires_in": 3599,
    "refresh_token": "0001112223334445556667778899aabbccddeeff"
}

Token Refresh

After initial password auth, the access_token can be renewed via an OAuth 2.0 refresh request.

• grant_type: refresh_token
• refresh_token: {your previously issued refresh token}
• client_id: {an arbitrary string describing your app}
• client_secret: {an arbitrary string}

cURL

Code
curl 'https://{your-domain}.aerion.app/oauth2/token' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -H 'origin: https://{your-domain}.aerion.app' 
  --data-raw 'grant_type=refresh_token&refresh_token={your-refresh-token}&client_id={your-app-name}&client_secret={must-be-present}'

JavaScript / Node.js Fetch

Code
fetch("https://{your-domain}.aerion.app/oauth2/token", {
  "headers": {
    "content-type": "application/x-www-form-urlencoded",
    "companyurl": "{your-domain}.aerion.app",
  }, 
  "body": "grant_type=refresh_token&refresh_token={your-refresh-token}&client_id={your-app-name}&client_secret={must-be-present}",
  "method": "POST",
});

Authenticating API Requests

Once an access_token has been retrieved, the token can be used in the authorization header as a bearer token.

Here are two examples to the “me” endpoint, showing info about the currently logged in user

cURL

Code
curl 'https://{your-domain}.aerion.app/v1/users/me' \
  -H 'authorization: Bearer {your-access-token}'

JavaScript / Node Fetch

Code
fetch('https://{your-domain}.aerion.app/v1/users/me', {
	"headers": {
		"authorization": 'Bearer {your-access-token}'
	},
});