Skip to content

t1k:users-mapping

FieldValue
Modulet1k-base
Version5.15.36
Effortlow
ToolsBash, Grep, Read

Keywords: cross-platform identity, discord id, github to discord, identity lookup, lark id, map user, mention user, plane user, slack id, telegram id, unified users, user lookup, user mapping, users-mapping, users.the1studio.org, who is this person, who is this user

/t1k:users-mapping
lookup <github|discord|slack|telegram|lark|plane|email|name>=<value>

Cross-platform user mapping — who is this person?

Section titled “Cross-platform user mapping — who is this person?”

One studio service maps a person’s identity across the six platforms we use, so a GitHub login can become the Discord id an embed needs, or a Slack id can become a human name.

FactValue
Serviceusers-mapping (a Cloudflare Worker, read-only)
Base URLhttps://users.the1studio.org
Audienceusers-mapping
Dataa mirror of ClaudeAssistant’s unified_users rows
Fields per persondisplayName, email, avatarUrl, and per platform *UserId / *Username for github, discord, slack, telegram, lark, plane
  • A GitHub login (or any platform id/username) must become another platform’s id — e.g. turning tuha263 into a discordUserId for a <@id> mention, or a slackUserId for a Slack mention.
  • An id in a log, a card or a payload must become a human name.
  • “Who is this person / do we know this account?” across platforms.
  • Anything that would otherwise build a second identity mapping. This is the SSOT — do not.

If the caller already runs inside the ClaudeAssistant compose network, call GET http://app-backend:3000/api/users directly instead: it is the live source, this Worker is a lagging mirror, and the hop stays on the internal network.

The Worker takes a studio-auth assertion whose audience includes users-mapping. Mint one with the kit helper, which exchanges your existing gh auth login once and caches a 1 h assertion:

Terminal window
H=$(bun ~/.claude/scripts/studio-auth-headers.cjs \
|bun -e 'let s="";process.stdin.on("data",d=>s+=d).on("end",()=>process.stdout.write(JSON.parse(s).Authorization))')

--auth-base https://auth-api.the1studio.org is optional on a current install (the helper defaults it from the kit config). The helper prints {"Authorization":"Bearer <assertion>"} on stdout and nothing on failure, so wrap it exactly as above. Never print, log or commit the assertion. A non-interactive job may instead read the vault token USERS_MAPPING_READ_TOKEN; same rule — the value never appears in output.

Three routes. GET /users returns every row; GET /users/lookup?... takes exactly one of github | discord | slack | telegram | lark | plane | email | name (a platform id or username both work; name is an accent- and case-insensitive word-prefix match); GET /status returns the mirror’s metadata only.

Terminal window
H=$(bun ~/.claude/scripts/studio-auth-headers.cjs \
|bun -e 'let s="";process.stdin.on("data",d=>s+=d).on("end",()=>process.stdout.write(JSON.parse(s).Authorization))')
# 1. GitHub login -> the whole cross-platform row (then read .discordUserId / .slackUserId)
curl -s -H "Authorization: $H" \
"https://users.the1studio.org/users/lookup?github=tuha263"
# 2. Discord id -> the person (name, avatar, every other platform id)
curl -s -H "Authorization: $H" \
"https://users.the1studio.org/users/lookup?discord=123456789012345678"
# 3. Name -> candidates, accent- and case-insensitive word-prefix
curl -s -H "Authorization: $H" \
"https://users.the1studio.org/users/lookup?name=nguyen"

Lookup answers {"users":[…],"matched":N,"meta":{…}}; /users answers {"users":[…],"meta":{…}}. A miss is not an error: it is HTTP 200 with users: [] and matched: 0. Read meta before trusting any of it.

  • The mirror lags the source by up to a day. It is republished by a daily sync plus a manual “Publish now” in the dashboard People tab. A person linked minutes ago is invisible here.
  • Check meta.stale first. meta.syncedAt says when the snapshot was published and meta.stale is true past the staleness window. stale: true means the rows may be out of date, not that the service is down.
  • email is null on most rows — they were matched on platform identity, not mail. Do not key a join on it; do not show a bare null.
  • matched can exceed the returned rows. A lookup caps its result set, so matched: 40 with 25 rows means 15 were withheld — narrow the query rather than reporting a truncated count.
  • A discordUserId match is not a guild membership. A row says who a person is, never which server they are in, so a technically-matching id can belong to an account in an unrelated guild (a name=manhND lookup once returned a “Playable Labs” account, and the DM reached the wrong person). Before DMing a resolved id, confirm it is a member of the studio guild RoadTo1M (961816115175120996) with a guild-scoped members_list / members_search; DM only ids that pass.
  • These rows are the same identity data ClaudeAssistant exposes; the Worker is a read-only mirror of them. Never write your own mapping alongside it.
SymptomMeaning and fix
401 {"error":"unauthenticated"}, or invalid_tokenNo assertion, or an expired/bad one. Re-run the helper; re-check gh auth login.
401/403 naming the audience or orgThe assertion was minted but this caller cannot reach the audience. Check org membership, then the audience registry in The1Studio/studio-auth.
400 {"error":"bad_request"}Zero or two-plus lookup params. Pass exactly one.
503 {"error":"not_synced"}The Worker has no snapshot yet — distinct from stale: true. Wait for a publish; do not retry in a loop.
users: [], matched: 0 at HTTP 200A clean miss. Fall back to the bare platform handle (@<login> text), never to a guessed id.
meta.stale: trueServing anyway, from an older snapshot. Say so if the answer drives a decision.
404 / 405Wrong path or method. PUT /sync is publisher-only — never call it.
  • docs/studio-auth.md — how a tool authenticates, and why a broker assertion rather than a token.
  • docs/mcp-studio-bearer.md — how a hosted studio service is registered and which audiences exist.
  • modules/t1k-base/rules/studio-auth-required.md — an internal tool MUST go through studio-auth.
  • The consumer-side contract (routes, limits, wire errors) is the SSOT in the ClaudeAssistant repository’s users-mapping-worker doc; read it there, do not restate it here.