Concepts
Member sessions and user keys

Member sessions and user keys

A community API key says which community is calling. Two more credentials say which person: a member session (or a short-lived member token) for a member of that community, and a user key for a person's own catalogue.

Member sessions

auth.signIn, auth.signUp, the emailed sign-in link and Continue with Google all return an embed session: a 30-day token bound to this one community. Send it in X-Cobuntu-Auth-Token, alongside the secret key, on member calls; the client does this on client.as(token).

  • It works only on this community's member routes (/me/*, member pricing, member tickets, the finance me/* routes), and only while the person is still a member there. The community in the token must match the key's community.
  • It is refused by every other Cobuntu API: other communities, direct messages, the person's account settings outside this community, their money in other communities. Stolen from your cookie store, it is useless anywhere but your own community.
  • A normal Cobuntu app session sent to a member route is 401 INVALID_SESSION. Only embed sessions are accepted there.
  • An expired or revoked session answers 401 INVALID_SESSION: clear your cookie and send the visitor to sign in.

Inside your community the session is the member, so store it like a password: an HttpOnly, Secure, SameSite=Lax cookie set by your server, never in localStorage or a client-readable cookie.

// Server only: the client for this request, acting for the member if signed in.
const token = cookies().get("cobuntu_session")?.value;
const client = token ? cobuntu.as(token) : cobuntu;

Embed in your own code walks through the cookie, sign-in and sign-out end to end.

Some reads take the session optionally: without it they answer for an anonymous visitor, with it they personalise (member prices, isAttending). The reference marks these "Member session: optional".

Member tokens for apps

An installed app that already knows a member's userId can mint a member token (APP_MINT_MEMBER_TOKEN) and send it as X-Cobuntu-Member-Token on the member-token routes (attendance status, RSVP, leave). It lives 5 minutes. See App handoff.

User keys

A second kind of credential, for reading one person's own catalogue. A user key belongs to a person rather than to a community, starts uk_ instead of ck_, and carries exactly one scope:

ScopeUsed by
READ_OWNreading your own products, courses and events

It is sent the same way as a community key:

X-API-Key: uk_...
Authorization: Bearer uk_...

The two kinds are not interchangeable: a community key on a user-level route is a 401, and a user key on a community route is a 401. They are separate credentials against separate tables, and the prefixes exist so a mix-up is visible before you deploy rather than after. There is no user-level wildcard.

Generate and revoke keys in the Cobuntu app under Settings → API. The raw key is shown once and stored only as a hash, so it cannot be retrieved later.

The routes, under /api/v1/users/me/..., are in the User keys area of the reference.

API keys and scopesSecurity model