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

# Authentication

> How to authenticate your requests to the Talview Graph API

All API requests to Talview must be authenticated using the **OAuth2 Protocol**. This ensures that only authorized systems can access your data and perform operations on the platform.
All queries and endpoints, but the authentication endpoints, require access tokens.

## Authorization Header

Once you have generated an access token, it must be included in the `Authorization` header of every API request as a Bearer token.

```http theme={null}
Authorization: Bearer <YOUR_ACCESS_TOKEN>
```

***

## Generate an Access Token

Talview provides a RESTful, as well as graphQL endpoint to obtain your access tokens. You will need the credentials (Username, Password, and Tenant ID) shared by Talview for your specific environment.

### Request Details

| Configuration     | Value                       |
| :---------------- | :-------------------------- |
| **Host**          | `https://api.talview.com`   |
| **Method**        | `POST`                      |
| **REST Route**    | `/api/rest/auth_user_login` |
| **graphQL Route** | `/v1/graphql`               |

### Request Body Schema

| Parameter   | Type    | Mandatory | Description                     |
| :---------- | :------ | :-------- | :------------------------------ |
| `username`  | String  | Yes       | Your Talview-provided username. |
| `password`  | String  | Yes       | Your Talview-provided password. |
| `tenant_id` | Integer | Yes       | Your unique Talview Tenant ID.  |

### RESTful Endpoint

#### Sample Request

<CodeGroup>
  ```bash cURL theme={null}
  curl --request POST \
    --url https://api.talview.com/api/rest/auth_user_login \
    --header 'Content-Type: application/json' \
    --data '{
      "username": "username@yourcompany.com",
      "password": "SecurePassword",
      "tenant_id": 1
    }'
  ```

  ```json Body theme={null}
  {
    "username": "username@yourcompany.com",
    "password": "SecurePassword",
    "tenant_id": 1
  }
  ```
</CodeGroup>

#### Sample Response

On success, the API returns an access token and a refresh token.

```json theme={null}
{
  "auth_user_login": {
    "success": true,
    "error_message": null,
    "data": {
      "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI...",
      "expires_in": 3600,
      "refresh_token": "d9865001-c918-4903-8209-..."
    }
  }
}
```

### GraphQL Endpoint

You can also obtain tokens using the `auth_user_login` mutation directly through the GraphQL endpoint. This is useful if you prefer to keep all interactions within GraphQL.

#### Sample Request

<CodeGroup>
  ```bash cURL theme={null}
  curl --request POST \
    --url https://api.talview.com/v1/graphql \
    --header 'Content-Type: application/json' \
    --data '{
      "query": "mutation MyMutation($password: String, $tenant_id: Int, $username: String) { auth_user_login(data: {password: $password, tenant_id: $tenant_id, username: $username}) { data { access_token expires_in refresh_token } } }",
      "variables": {
        "username": "username@yourcompany.com",
        "password": "SecurePassword",
        "tenant_id": 1
      }
    }'
  ```

  ```graphql Mutation theme={null}
  mutation MyMutation($password: String = "", $tenant_id: Int = 10, $username: String = "") {
    auth_user_login(data: {password: $password, tenant_id: $tenant_id, username: $username}) {
      data {
        access_token
        expires_in
        refresh_token
      }
    }
  }
  ```

  ```json Variables theme={null}
  {
    "username": "username@yourcompany.com",
    "password": "SecurePassword",
    "tenant_id": 1
  }
  ```
</CodeGroup>

#### Sample Response

On success, the API returns an access token and a refresh token.

```json theme={null}
{
  "auth_user_login": {
    "success": true,
    "error_message": null,
    "data": {
      "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI...",
      "expires_in": 3600,
      "refresh_token": "d9865001-c918-4903-8209-..."
    }
  }
}
```