# Organization membership metadata
## The three metadata scopes
Clerk has user metadata (about the person everywhere), organization metadata
(about the org), and membership metadata (about this person's membership in
this org). Most agents reach for user metadata for everything and then
wonder why a user's team is wrong in their second org.
Use membership metadata for anything that is true of the person only inside
one org: team assignment, seat type, cost center, start date, manager.
## The order
1. Write membership metadata through the backend API when the membership is
created or updated (invitation acceptance and role changes are the two
natural moments).
2. Read it server side from the membership object when you need it in
backend code.
3. To make it available on every request without an API call, expose it via
custom session token claims. The org context in claim templates lets you
reference membership-scoped data.
4. Keep the claim small: ids and flags, not documents.
## The traps
- Membership metadata is per (user, org) pair. A user in two orgs has two
independent membership metadata objects. Code that reads "the user's
team" without specifying the org is a bug.
- Membership metadata does not replace roles. If an attribute gates access
(can this person approve invoices), that is a permission on a role, not
a metadata flag. Metadata describes; roles authorize.
- The session token only carries membership context for the active org.
Switching orgs changes what the claims contain.
## Checklist
- Audit who can write membership metadata. If any member can edit their own
team to "executive", it is display data, not trust data.
- On membership deletion, decide whether the metadata is archived with it
or dropped. For billing-relevant attributes, archive.