Companion Player API — external reader map
Status: Locked 2026-11-12
Contract: FS-API-001–007, AC-API-001 · FE Spec Settings → Social companion profile privacy · Architecture Map P9c
GDD chapter: companion-player-api
Programming Bible: docs/31-companion-player-api.md
Does not replace: invite Discord (FS-SOC-004 / FS-ID-*) or MonetaryPlatform AntiCheat
Use an app key + component profile pattern so a separate companion Discord bot (and later BenchMark / third-party sites) can read Online player info without inventing a second career store.
External companion pattern → TFA
Section titled “External companion pattern → TFA”| Common companion pattern | Terra Firma |
|---|---|
| App registration + API key | Studio app registration + X-API-Key |
| Membership ID | EOS PUID |
| Character ID | Online character GUID |
| Display-name search | GET /v1/memberships/search?displayname= |
| Profile components query | GET /v1/profiles/{puid}?components= |
| OAuth “as user” | Optional later Authorization: Bearer for private / Friends components |
| Manifest / defs | GET /v1/manifest/{entityType}/{hash} |
| Clan summary | Clan tag on Profiles (roster detail stays in-game Social) |
| Triumphs / Records | FS-CAR-003 Triumphs |
| Metrics / career | FS-CAR-001–004 |
| Leaderboards | FS-CAR-005 + site BenchMark |
| Activity history | FS-MCH-006 (default Friends) |
| Equipment (public) | Equipped cosmetics only (FS-NET-002) |
Components (reuse FS §19 — do not invent stats)
Section titled “Components (reuse FS §19 — do not invent stats)”| Component | Backed by | Default |
|---|---|---|
Profiles |
PUID, display name, opaque Discord id, clan tag | Public |
Characters |
Name, Order / Faction, level, subclass unlocks | Public |
CharacterEquipment |
Equipped IDs / cosmetic hashes | Public (lockable) |
Career |
FS-CAR-001 | Public (lockable) |
CollectionsMastery |
FS-CAR-002 | Public (lockable) |
Triumphs |
FS-CAR-003 | Public (lockable) |
ModeAggregates |
FS-CAR-004 | Public (lockable) |
LadderStanding |
FS-CAR-005 | Public when ranked |
MatchHistory / LastMatchRecap |
FS-MCH-006 / FS-MCH-002 | Friends (lockable) |
Hard deny: bags / Secure Locker, Credits / BTUCOIN / LUMENAR, marketplace listings, Case / mystery / OV clues, Trust / reports / ghost, chat, Solo pool, secrets / Discord tokens, others’ fireteam Accept / Join, any write / mutate.
Two Discord products (hard split)
Section titled “Two Discord products (hard split)”| Invite Discord | Companion Discord bot | |
|---|---|---|
| Discord application | Game client / invite delivery | Separate app |
| Purpose | Link account + deliver invite deep links | /stats, /ladder, profile cards |
| Auth | Discord OAuth → EOS_Connect_LinkAccount |
Companion API X-API-Key (+ optional player OAuth later) |
| Writes game state | Invite tokens via game server | None (read-only) |
| FS | FS-ID-*, FS-SOC-004 | FS-API-* |
Linked Discord on a PUID enables GET /memberships/by-discord/{discordUserId} for the companion bot. That lookup is identity bridge only — not invite authority.
Suggested ship order (after locks)
Section titled “Suggested ship order (after locks)”- Manifest + Ladder board
- Membership search +
Characters+Career - Equipment / Collections / Triumphs
- Discord-id membership bridge
- Match History + player OAuth
- Third-party app key portal
Out of scope (v1)
Section titled “Out of scope (v1)”Loadout writes, presence / instance join from the bot, Case / Pre-CF mystery, replacing EOS Friends with Discord friends, building the Discord bot repo itself.