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:

{
  "organizationId": "uuid"
}

Response (200):

{
  "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):

{
  "enabled": true,
  "baseUrl": "https://chat.equa.cc"
}

When Mattermost is not configured:

{
  "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):

{
  "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):

{
  "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):

{
  "valid": true
}

When the token is invalid or missing:

{
  "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):

{
  "userId": "550e8400-e29b-41d4-a716-446655440000"
}

When no mapping exists:

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