GFAVIP Matrix Server API

Server Configuration

Setting	Value
Homeserver URL	https://chat.gfavip.com
Server Name	gfavip.com
Matrix Protocol	r0.0.1 through v1.11

Authentication Flow

Step 1: Get GFAVIP Session Token

Your app should have the user's GFAVIP session token in the format:

gfavip-session-{randomHex}

Step 2: Request Matrix Token

POST/api/auth/matrix-token

Headers:
  Authorization: Bearer gfavip-session-{your-token}
  Content-Type: application/json

Body: (empty)

Response

{
  "accessToken": "syt_c3NvX..._1A2B3C",
  "userId": "@sso_{uuid}:gfavip.com",
  "homeServer": "gfavip.com"
}

Step 3: Initialize Matrix Client

import * as sdk from 'matrix-js-sdk';

const matrixClient = sdk.createClient({
  baseUrl: "https://chat.gfavip.com",
  accessToken: response.accessToken,
  userId: response.userId
});

await matrixClient.startClient();

API Endpoints

GET/health

Health check endpoint

{"status": "healthy", "service": "gfavip-matrix-server"}

GET/config

Server configuration status

{"gfavip_sso_configured": true, "mode": "production"}

GET/_matrix/client/versions

Matrix protocol version discovery

GET/.well-known/matrix/client

Matrix server discovery

Room Creation Best Practices

Creating Direct Messages

const room = await client.createRoom({
  is_direct: true,
  invite: [otherUserId],
  preset: 'trusted_private_chat'  // Auto-joins creator
});

// Ensure you're joined
await client.joinRoom(room.room_id);

Getting Room Display Names

// Use getMembers() to include invited members
const members = room.getMembers();
const otherMembers = members.filter(m => m.userId !== myUserId);
const roomName = otherMembers[0]?.name || 'New conversation';

Common Issues & Solutions

403 "User not in room" Error

The room creator isn't properly joined. Use preset: 'trusted_private_chat' or call joinRoom() after creation.

"Empty room" Display

Use room.getMembers() instead of room.getJoinedMembers() to include invited members.

Filter 404 Errors

These are normal. The Matrix SDK tries to get a cached filter first (returns 404), then creates a new one. This is expected behavior.

Security Notes

• CORS: Enabled for all origins (development)
• SSO Validation: All tokens validated against wallet.gfavip.com
• Token Format: gfavip-session-{randomHex} (256-bit random)
• HTTPS: Required for all production endpoints