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

# Mattermost Endpoints

> API endpoints for Mattermost messaging integration

# Mattermost Endpoints

Endpoints for managing Mattermost team messaging sessions, configuration, and organization sync.

> `Source: equa-server/modules/agent/src/mattermost/mattermost-endpoints.ts`

***

## POST /api/v1/mattermost/session

Provisions a Mattermost user and team for the current user and organization, then returns a session token for iframe embedding.

**Authentication:** Cookie (Equa session)

**Request Body:**

```json theme={null}
{
  "organizationId": "uuid"
}
```

**Response (200):**

```json theme={null}
{
  "token": "gxpwutnk3bdjpd8y8s69k4cfny",
  "baseUrl": "https://chat.equa.cc",
  "teamName": "acme-corp",
  "mmUserId": "cqh9a9u8wi8i5neqwkfxdntq7a"
}
```

**Error Responses:**

| Status | Condition                                                                            |
| ------ | ------------------------------------------------------------------------------------ |
| 401    | No valid session cookie                                                              |
| 403    | User is not a member of the organization                                             |
| 500    | Mattermost not configured (`MATTERMOST_URL` or `MATTERMOST_ADMIN_BOT_TOKEN` missing) |

**Behavior:**

1. Validates session cookie and org membership
2. Calls `ensureUser()` -- creates Mattermost user if not exists, stores mapping
3. Calls `issueSessionToken()` -- creates personal access token, AES-encrypts and stores
4. Calls `ensureTeam()` -- creates Mattermost team with default channels if not exists
5. Calls `ensureTeamMembership()` -- adds user to team if not already a member
6. Returns token and connection details

> `Source: equa-server/modules/agent/src/mattermost/mattermost-endpoints.ts, Line: 34`

***

## GET /api/v1/mattermost/config

Returns Mattermost configuration status for the frontend.

**Authentication:** Cookie (Equa session)

**Response (200):**

```json theme={null}
{
  "enabled": true,
  "baseUrl": "https://chat.equa.cc"
}
```

When Mattermost is not configured:

```json theme={null}
{
  "enabled": false,
  "baseUrl": null
}
```

> `Source: equa-server/modules/agent/src/mattermost/mattermost-endpoints.ts, Line: 110`

***

## GET /api/v1/mattermost/team-mapping/:teamId

Maps a Mattermost team ID to an Equa organization ID. Used by equabot-gateway to resolve org context for agent interactions.

**Authentication:** Bearer token (gateway auth token)

**Path Parameters:**

| Parameter | Type   | Description        |
| --------- | ------ | ------------------ |
| `teamId`  | string | Mattermost team ID |

**Response (200):**

```json theme={null}
{
  "organizationId": "550e8400-e29b-41d4-a716-446655440000"
}
```

**Error Responses:**

| Status | Condition                                   |
| ------ | ------------------------------------------- |
| 401    | Invalid or missing Bearer token             |
| 404    | No organization mapped to the given team ID |

> `Source: equa-server/modules/agent/src/mattermost/mattermost-endpoints.ts, Line: 127`

***

## POST /api/v1/mattermost/sync-org/:orgId

Triggers a full synchronization of Equa organization members to the corresponding Mattermost team. Adds missing members and removes members no longer in the org.

**Authentication:** Cookie (Equa session, must have org admin permissions)

**Path Parameters:**

| Parameter | Type | Description          |
| --------- | ---- | -------------------- |
| `orgId`   | UUID | Equa organization ID |

**Response (200):**

```json theme={null}
{
  "synced": 5
}
```

| Field    | Type   | Description                                           |
| -------- | ------ | ----------------------------------------------------- |
| `synced` | number | Number of members synchronized to the Mattermost team |

**Error Responses:**

| Status | Condition                                      |
| ------ | ---------------------------------------------- |
| 401    | No valid session cookie                        |
| 403    | User does not have access to this organization |
| 500    | Mattermost not configured or sync failed       |

> `Source: equa-server/modules/agent/src/mattermost/mattermost-endpoints.ts, Line: 150`

***

## GET /api/v1/mattermost/token-health

Validates the authenticated user's stored Mattermost personal access token by checking it against the Mattermost server. Used by the frontend for periodic session health monitoring.

**Authentication:** Cookie (Equa session)

**Response (200):**

```json theme={null}
{
  "valid": true
}
```

When the token is invalid or missing:

```json theme={null}
{
  "valid": false,
  "reason": "no_token"
}
```

| Field    | Type              | Description                                                                  |
| -------- | ----------------- | ---------------------------------------------------------------------------- |
| `valid`  | boolean           | Whether the stored PAT is still accepted by Mattermost                       |
| `reason` | string (optional) | `"no_token"` if no token is stored, `"check_failed"` if verification errored |

**Error Responses:**

| Status | Condition               |
| ------ | ----------------------- |
| 401    | No valid session cookie |

> `Source: equa-server/modules/agent/src/mattermost/mattermost-endpoints.ts`

***

## GET /api/v1/mattermost/user-mapping/:mmUserId

Maps a Mattermost user ID to an Equa user ID. Used by equabot-gateway to resolve sender identity for org-scoped agent interactions.

**Authentication:** Bearer token (gateway auth token via `EQUA_GATEWAY_TOKEN`)

**Path Parameters:**

| Parameter  | Type   | Description        |
| ---------- | ------ | ------------------ |
| `mmUserId` | string | Mattermost user ID |

**Response (200):**

```json theme={null}
{
  "userId": "550e8400-e29b-41d4-a716-446655440000"
}
```

When no mapping exists:

```json theme={null}
{
  "userId": null
}
```

**Error Responses:**

| Status | Condition                       |
| ------ | ------------------------------- |
| 401    | Invalid or missing Bearer token |
| 500    | Lookup failed                   |

> `Source: equa-server/modules/agent/src/mattermost/mattermost-endpoints.ts`