# 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`](http://api.coffeecup.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

```sql
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

```jsx
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).

```jsx
{
    "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

```jsx
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

```jsx
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

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

### JavaScript / Node Fetch

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