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:

Validates session cookie and org membership
Calls ensureUser() — creates Mattermost user if not exists, stores mapping
Calls issueSessionToken() — creates personal access token, AES-encrypts and stores
Calls ensureTeam() — creates Mattermost team with default channels if not exists
Calls ensureTeamMembership() — adds user to team if not already a member
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

Platform API

Gateway API

CLI Reference

Mattermost Endpoints

Mattermost Endpoints

POST /api/v1/mattermost/session

GET /api/v1/mattermost/config

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

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

GET /api/v1/mattermost/token-health

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

​Mattermost Endpoints

​POST /api/v1/mattermost/session

​GET /api/v1/mattermost/config

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

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

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

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

Mattermost Endpoints

POST /api/v1/mattermost/session

GET /api/v1/mattermost/config

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

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

GET /api/v1/mattermost/token-health

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