> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cynopsis.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> Setting up Athena authentication access

<Info>
  **Prerequisite**: In order to run the collection below,
  a **host** URL is required, which will be provided by Cynopsis. This can then be set as a global variable
  or in the environment created for Athena in the Introduction section.
</Info>

This documentation covers two methods for obtaining authentication tokens:

1. **Amazon Cognito User Pools API**: The original method for getting tokens via Cognito.
2. **CRM System API**: A newer method for getting tokens directly via the CRM.

***

## Method 1: Using Amazon Cognito User Pools API

To get a Cognito access token, we are using the Amazon Cognito User Pools API.

[Postman Authentication Service Collection](https://developer.cynopsis.co/assets/postman-collections/athena3-auth.json)

### Health Check of the Authentication API Service

```bash theme={null}
GET {{host}}/auth/healthCheck
```

**Sample HTTP Response**

```bash theme={null}
Expected Response Code: 200
Response Body:
e.g.
{
    "description": "the service is healthy"
}
```

### Get Access Token by Username

To generate a token, please make an API call to the following API.

```bash theme={null}
POST {{host}}/auth/get-access-token-by-username
```

### Requirements

For the credentials required below, Cynopsis will advise.

* username
* password
* user\_pool\_id
* client\_id

**Sample HTTP Request**

```bash theme={null}
HTTP Method: POST
URL: {{host}}/auth/get-access-token-by-username
Request Body:
e.g.
{
    "username": "username@mycredentials.com",
    "password": "Th15Is@P4S5W0rd!",
    "user_pool_id": "Cynopsis to advise",
    "client_id": "Cynopsis to advise"
}
```

**Sample HTTP Response**

```bash theme={null}
Expected Response Code: 200
Response Body:
e.g.
{
    "token": "Token will be here.",
    "id_token": "ID of token will be here."
}
```

### Get Refresh Token

```bash theme={null}
POST {{host}}/auth/get-refresh-token
```

**Sample HTTP Request**

Same requirements as the **Get Access Token by Username** endpoint.

```bash theme={null}
HTTP Method: POST
URL: {{host}}/auth/get-access-token-by-username
Request Body:
e.g.
{
    "username": "username@mycredentials.com",
    "password": "Th15Is@P4S5W0rd!",
    "user_pool_id": "Cynopsis to advise",
    "client_id": "Cynopsis to advise"
}
```

**Sample HTTP Response**

```bash theme={null}
Expected Response Code: 200
Response Body:
e.g.
{
    "refresh_token": "Token will be here.",
    "id_token": "ID of token will be here."
}
```

### Get Access Token by Refresh Token

**Sample HTTP Request**

Make an API call to the above API and then use that refresh token in this API along with the client ID.

```bash theme={null}
HTTP Method: POST
URL: {{host}}/auth/get-access-token-by-refresh-token
Request Body:
e.g.
{
    "refresh_token": "Refresh token will be required here.",
    "client_id": "Cynopsis to advise"
}
```

**Sample HTTP Response**

```bash theme={null}
Expected Response Code: 200
Response Body:
e.g.
{
    "refresh_token": "Token will be here.",
    "id_token": "ID of token will be here."
}
```

### Authenticate Token

To authenticate a token, make an API call to the following API.

```bash theme={null}
POST {{host}}/auth/authenticate-token
```

**Sample HTTP Request**

```bash theme={null}
HTTP Method: POST
URL: {{host}}/auth/authenticate-token
Request Body:
e.g.
{
    "token": "Token to be authenticated.",
    "pool_url": "Cynopsis to advise",
    "client_id": "Cynopsis to advise"
}
```

**Sample HTTP Response**

For security reasons, the properties of the response body have been set to an empty string.

```bash theme={null}
Expected Response Code: 200
Response Body:
e.g.
{
    "origin_jti": "",
    "sub": "",
    "event_id": "",
    "token_use": "",
    "scope": "",
    "auth_time": "",
    "iss": "",
    "exp": "",
    "iat": "",
    "jti": "",
    "client_id": "",
    "username": ""
}
```

***

## Method 2: Using the CRM System API

This method allows you to get access and refresh tokens directly from the CRM system.

### Get Access Token and Refresh Token by Username and Password on CRM

To generate a token and refresh token, please make an API call to the following endpoint.

```bash theme={null}
POST {{host}}/oauth/token
```

### Requirements

For the credentials required below, Cynopsis will advise.

* grant\_type
* client\_id
* username
* password

**Sample HTTP Request**

```bash theme={null}
HTTP Method: POST
URL: {{host}}/oauth/token
Request Body:
e.g.
{
    "grant_type": "password",
    "client_id": "client_id",
    "username": "clientsuccess@cynopsis.co",
    "password": "pw@123"
}
```

**Sample CURL Request**

```bash theme={null}
curl --location '{{host}}/oauth/token' --header 'Content-type: application/x-www-form-urlencoded' --data-urlencode 'grant_type=password' --data-urlencode 'client_id=client_id' --data-urlencode 'username=clientsuccess@cynopsis.co' --data-urlencode 'password=pw@123'
```

**Sample HTTP Response**

```bash theme={null}
Expected Response Code: 200
Response Body:
e.g.
{
    "access_token": "Access token will be here.",
    "token_type": "bearer",
    "refresh_token": "Refresh token will be here",
    "expires_in": 86399,
    "scope": "read,write",
    "sub": "",
    "iss": "https://crm",
    "identifier_provider": "CRM",
    "jti": ""
}
```

### Get Access Token by Refresh Token (CRM)

Make an API call to the above API and then use that refresh token in this API along with the client ID.

**Sample HTTP Request**

```bash theme={null}
HTTP Method: POST
URL: {{host}}/oauth/token
Request Body:
e.g.
{
    "grant_type": "refresh_token",
    "client_id": "Cynopsis to advise",
    "refresh_token": "Refresh token obtained from the above request"
}
```

**Sample CURL Request**

```bash theme={null}
curl --location '{{host}}/oauth/token' --header 'Content-Type: application/x-www-form-urlencoded' --data-urlencode 'grant_type=refresh_token' --data-urlencode 'client_id=client_id' --data-urlencode 'refresh_token=refresh token obtained from the above request'
```

**Sample HTTP Response**

```bash theme={null}
Expected Response Code: 200
Response Body:
e.g.
{
    "access_token": "New access token will be here.",
    "token_type": "bearer",
    "refresh_token": "New refresh token will be here",
    "expires_in": 86399,
    "scope": "read,write",
    "sub": "",
    "iss": "https://crm",
    "identifier_provider": "CRM",
    "jti": ""
}
```

***

**Note:** Choose the authentication method that best fits your integration needs. Both methods provide secure access to Athena services, with the CRM method offering a more direct token generation approach.

***