t1k:users-mapping
| Field | Value |
|---|---|
| Module | t1k-base |
| Version | 5.15.36 |
| Effort | low |
| Tools | Bash, 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
How to invoke
Section titled “How to invoke”/t1k:users-mappinglookup <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.
| Fact | Value |
|---|---|
| Service | users-mapping (a Cloudflare Worker, read-only) |
| Base URL | https://users.the1studio.org |
| Audience | users-mapping |
| Data | a mirror of ClaudeAssistant’s unified_users rows |
| Fields per person | displayName, email, avatarUrl, and per platform *UserId / *Username for github, discord, slack, telegram, lark, plane |
When to use it
Section titled “When to use it”- A GitHub login (or any platform id/username) must become another platform’s id — e.g. turning
tuha263into adiscordUserIdfor a<@id>mention, or aslackUserIdfor 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.
Authenticate (every call)
Section titled “Authenticate (every call)”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:
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.
Call it
Section titled “Call it”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.
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-prefixcurl -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.
Hard rules
Section titled “Hard rules”- 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.stalefirst.meta.syncedAtsays when the snapshot was published andmeta.staleistruepast the staleness window.stale: truemeans the rows may be out of date, not that the service is down. emailis null on most rows — they were matched on platform identity, not mail. Do not key a join on it; do not show a barenull.matchedcan exceed the returned rows. A lookup caps its result set, somatched: 40with 25 rows means 15 were withheld — narrow the query rather than reporting a truncated count.- A
discordUserIdmatch 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 (aname=manhNDlookup 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-scopedmembers_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.
Failure modes
Section titled “Failure modes”| Symptom | Meaning and fix |
|---|---|
401 {"error":"unauthenticated"}, or invalid_token | No assertion, or an expired/bad one. Re-run the helper; re-check gh auth login. |
401/403 naming the audience or org | The 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 200 | A clean miss. Fall back to the bare platform handle (@<login> text), never to a guessed id. |
meta.stale: true | Serving anyway, from an older snapshot. Say so if the answer drives a decision. |
404 / 405 | Wrong path or method. PUT /sync is publisher-only — never call it. |
Related
Section titled “Related”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-workerdoc; read it there, do not restate it here.