# Authentication Bot Apps Flows 

This article documents the final version of the diagram that shows the flow integrated into Humand App.

## General process overview

```mermaid
sequenceDiagram
    autonumber
    actor Admin
    participant BotApp as Bot App
    participant Humand as Humand API

    Note over Admin,Humand: Admin creates a Bot App
    Admin->>+Humand: Create Bot App
    Humand-->>-Admin: Return clientId and clientSecret
    Admin->>+Humand: Assign permissions to Bot App

    Note over Admin,BotApp: Admin configures the Bot App
    Admin->>+BotApp: Provide clientId and clientSecret
    BotApp-->>BotApp: Store clientId and clientSecret securely

    Note over BotApp,Humand: Bot App authenticates with Humand
    BotApp->>+Humand: Log in using clientId and clientSecret
    Humand-->>-BotApp: Return accessToken and refreshToken

    Note over BotApp: Bot App stores tokens securely
    BotApp-->>BotApp: Store accessToken and refreshToken securely

    Note over BotApp,Humand: Bot App uses Humand endpoints
    BotApp->>+Humand: Make API requests using accessToken
    Humand-->>-BotApp: Respond with requested data

    Note over BotApp,Humand: Handle expired access token
    BotApp->>+Humand: Refresh accessToken using refreshToken
    Humand-->>-BotApp: Return new accessToken and refreshToken

    Note over BotApp,Humand: Handle expired access and refresh tokens
    BotApp->>+Humand: Re-login using clientId and clientSecret
    Humand-->>-BotApp: Return new accessToken and refreshToken
```

## New endpoints for BotApps Manage From Admin

### Associated capabilities

VIEW_BOT_APPS,MANAGE_BOT_APPS

### Create Bot App

**Endpoint:** `POST /api/v1/backoffice/bot-apps`

**Authorization:** `Bearer {{adminToken}}`

**Request:**
```http
POST /api/v1/backoffice/bot-apps
Authorization: Bearer {{adminToken}}

{
    "name": "Example Bot App"
}
```
**Response:**
```json
{
    "id": 1,
    "clientId": "hu-7bddfb3f-3502-4cc3-b97c-1abb683b9d36",
    "clientSecret": "efgh5678",
    "instanceId": 34,
    "createdBy": 1
}
```
## New endpoints for BotApps Auth Flow

### Login

**Endpoint:** `POST /api/v1/botapps/auth/login` 

**Request:**
```http
POST /api/v1/botapps/auth/login
{
    "clientId": "hu-7bddfb3f-3502-4cc3-b97c-1abb683b9d36",
    "clientSecret": "kON0hFMG9PbQf3oIoD+0DXhMR9CKqAkZSX5oAHiXQaQ=",
    "instanceId": 34
}
```
**Response:**
```json
{
    "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "botApp": {},
    "instance": {},
    "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}
```
### Refresh

**Endpoint:** `GET /api/v1/botapps/auth/refresh`

**Authorization:** `Bearer {{refreshToken}}` 

**Request:**
```http
GET /api/v1/botapps/auth/refresh
Authorization: Bearer {{refreshToken}}
```
**Response:**
```json
{
    "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}
```
### Logout

**Endpoint:** `POST /api/v1/botapps/auth/logout`

**Authorization:** `Bearer {{accessToken}}` 

**Request:**
```http
POST /api/v1/botapps/auth/logout
Authorization: Bearer {{accessToken}}
```
**Response:**
```json
{
    "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}
```
## How BotApps Make Request

We have a especific groups of routers for BotApps under scope of `/api/v1/botapps`

### Bot App Data

**Endpoint:** `POST /api/v1/botapps/me`

**Authorization:** `Bearer {{accessToken}}` 

**Request:**
```http
POST /api/v1/botapps/me
Authorization: Bearer {{accessToken}}
```
**Response:**
```json
{
    "clientId": "hu-7bddfb3f-3502-4cc3-b97c-1abb683b9d36",
    "id": "1",
    "instanceId": 34,
    "name": "Example Bot App"
}
```

## How BotApps Impersonate Users

Bot Apps can impersonate a user to access resources within the scope of apps. To achieve this, a custom header must be set in the API requests.

**Important:** To successfully access a resource when a Bot App is impersonating a user, both the Bot App and the user must have the necessary capabilities assigned.

**Note:** The router must be configured to allow Bot Apps. This is done using the middleware `validateBotAppPermissions`.  

- **Middleware:** `validateBotAppPermissions`  
- **Parameter:** `capabilities` (optional) – An array of strings representing the required permissions for the route.

**Clarification:** Even if the route does not require specific permissions, the middleware is still necessary for the route to be accessed by a Bot App. In such cases, the middleware should be called without parameters.

### Example Usage

#### Route Requiring Permissions
```typescript
router.get(
    '/day-summary',
    validateBotAppPermissions([CapabilityName.VIEW_TIME_TRACKING]),
    entriesController.getRecentDaySummary
);
```

### Get User Data

**Endpoint:** `GET /api/v1/users/me`  

**Authorization:** `Bearer {{accessToken}}`  

**Header:** `X-Humand-User-Id: <user_id>`  

**Request:**
```http
GET /api/v1/users/me
Authorization: Bearer {{accessToken}}
X-Humand-User-Id: <user_id>
```

**Response:**
```json
{
    "user": {},
    "instance": {}
}
```