You will have workspaces in your app: a user creates an organization, invites colleagues by email, members hold roles that grant permissions, your own routes require a role or a permission, and your own queries join the membership. On top of that, as far as you need it: an active organization per session, invitations that can be rejected and canceled, teams inside an organization, roles your app defines at start-up or each organization creates at run time, and hooks around every change. An invitation can be accepted only by someone who has proved they own the invited address.
- An app with email sign-in, as in your first app. By default the organization plugin requires the email plugin: invitations are addressed to email, and
auth.Newfails without it. A phone-only or username-only app invites by another kind, or adds members only from the server; see Inviting by phone, or not at all. - The example is
examples/organizations: Alice creates Acme and invites Bob, Bob accepts once his address is verified, and two app pages are guarded by role.go run ./organizationsinexamples/serves it onlocalhost:8081;go test ./organizationsruns it. The transcripts below come from that program. - Steps 9 and 12 to 14 and inviting by phone are built from a second example,
examples/org-teams: teams, the active organization and team, a role Acme creates for itself, typed hooks, and invitations by email and by text message.go run ./org-teamsserves it onlocalhost:8081;go test ./org-teamsruns the whole flow, two users and a phone number included. - The plugin is its own module (
go get github.com/ubgo/auth/plugin/organization), because organizations are not authentication: an app with no groups never carries the code, and the plugin can be redesigned (nested levels, app-defined permissions) without touching the core. - What the plugin owns:
auth_org,auth_org_member,auth_org_inviteandauth_org_active(each session's active organization and team), plusauth_org_teamandauth_org_team_memberwithorganization.Teams, andauth_org_rolewithorganization.DynamicRoles. No foreign keys: deleting an organization, a member or a user removes the rows in Go, in one transaction. - Roles are
owner,adminandmemberout of the box, with default permissions; a role is a set of permission statements from the access module, so an app adds its own roles and resources the same way. A member may hold several roles.
Add organization.New() next to the email plugin. The invitation mail needs a page to link to, so either auth.WithBaseURL is set (the link is then the base URL plus /invitations) or organization.InviteLink names one.
newAuth · examples/organizations/main.go:110-120
func newAuth(db *sql.DB, m email.Mailer) (*auth.Auth, error) {
return auth.New(
auth.WithDB(db, sqlb.SQLiteDialect{}),
auth.WithBaseURL(baseURL),
auth.WithPlugins(
email.New(email.Login(), email.Recover(), email.WithMailer(m), email.Templates(mailTemplates)),
password.New(),
organization.New(),
),
)
}Check: auth.New refuses a setup nobody could be invited in. Without the email plugin: auth: plugin dependency not registered: "organization" requires "email". Without a base URL or InviteLink: auth: plugin "organization": organization: invitation links need auth.WithBaseURL or organization.InviteLink.
POST /auth/organization/create with a name and a slug. The slug appears in URLs, so it is 2 to 48 lowercase letters, digits and dashes and may not start with a dash; it is lowercased before the check, and it is unique across the deployment. The creator becomes the owner.
O='Origin: http://localhost:8081'
curl -s -b alice.txt -X POST localhost:8081/auth/organization/create -H "$O" -d '{"name":"Acme","slug":"-Acme"}'
curl -s -b alice.txt -X POST localhost:8081/auth/organization/create -H "$O" -d '{"name":"Acme","slug":"Acme"}'
curl -s -b alice.txt -X POST localhost:8081/auth/organization/create -H "$O" -d '{"name":"Acme 2","slug":"acme"}'{"error":{"code":"organization.bad_slug","message":"Use lowercase letters, digits and dashes."}}
{"id":"org_7n2gshuichmdexqwfljzp56x","slug":"acme","name":"Acme","createdAt":"2026-10-01T05:19:20.39302Z"}
{"error":{"code":"organization.slug_taken","message":"This address is already in use."}}From Go: org.Create(ctx, organization.CreateRequest{Name: "Acme", Slug: "acme"}) returns the Org; ctx must carry the signed-in request (a.WithRequest). org.List(ctx) returns the caller's organizations with their role in each:
curl -s -b alice.txt localhost:8081/auth/organization/list{"orgs":[{"id":"org_7n2gshuichmdexqwfljzp56x","slug":"acme","name":"Acme","createdAt":"2026-10-01T05:19:20.39302Z","role":"owner"}]}An admin or owner invites an address with a role no higher than their own. The address is normalized and stored, and a mail goes out through the email plugin with purpose organization.invite. Invitations are limited to 50 per hour per client address.
curl -s -b alice.txt -X POST localhost:8081/auth/organization/invite -H "$O" \
-d '{"orgId":"org_7n2gshuichmdexqwfljzp56x","email":"Bob@Example.com","role":"member"}'{"ok":true}
2026/10/01 10:49:20 mail to=bob@example.com subject="You are invited to join a team"
You were invited to join an organization. Sign in with this address, verify it if you have not, and accept the invitation here:
http://localhost:8081/invitations
The example words the mail itself with email.Templates; without that, the plugin's own wording goes out ("You are invited to join an organization", with the link at the end):
mailTemplates · examples/organizations/main.go:126-131
func mailTemplates(m auth.Message) (subject, text string) {
if m.Purpose == organization.PurposeInvite {
return inviteSubject, inviteText + m.Link
}
return email.DefaultTemplates(m)
}Every invitation message also carries a typed payload, m.Data, an organization.InvitationData (type-safe template variables): the invitation id, the invited address and role, the team, the expiry, the organization's id, name, slug and logo, and the inviter's id, name and primary verified address. A template reads it with a type assertion, so a renamed field is a compile error, not an empty line in a mail:
if d, ok := m.Data.(organization.InvitationData); ok {
return d.InviterName + " invited you to " + d.OrganizationName, "Join as " + string(d.Role) + ":\n\n" + m.Link
}Under auth.WithDeliveryOutbox the message is stored as JSON and sent later; the plugin implements auth.MessageDataDecoder, so the template still receives an InvitationData, never a map.
A role outside owner, admin, member is 400 organization.bad_role:
curl -s -b alice.txt -X POST localhost:8081/auth/organization/invite -H "$O" \
-d '{"orgId":"org_7n2gshuichmdexqwfljzp56x","email":"dave@example.com","role":"root"}'{"error":{"code":"organization.bad_role","message":"This role does not exist."}}Invitations are addressed by email unless organization.InviteBy(kinds...) names other identifier kinds: organization.InviteBy(phone.KindPhone) for a phone-only app, organization.InviteBy(email.KindEmail, phone.KindPhone) for either. The request then names the invitee as {"kind":"phone","identifier":"+14155550123","role":"member"} (the email field still works and means kind email; kind may be left out when only one kind is allowed). The value is normalized by its kind, the invitation is delivered through that kind's plugin (an SMS for phone), and it is accepted only by a user holding a verified identity of that kind and value, exactly as for email. Every kind must be registered by an identifier plugin, or auth.New fails; the email plugin is required only when email is among the kinds. A kind whose plugin cannot deliver messages (username) fails auth.New with auth.ErrNoDeliverer (the plugin asks auth.Config.CanDeliver at start-up), rather than the first invite. Naming both email and identifier, or a kind InviteBy does not allow, is 400 organization.invite_address. Invitations carry kind and identifier for every kind, and email only for an email invitation.
The org-teams example invites by either kind. Its newAuth is in Step 12; inviting Carol by her number, as she would type it:
curl -s -b alice.txt -X POST localhost:8081/auth/organization/invite -H 'Origin: http://localhost:8081' \
-d '{"kind":"phone","identifier":"+1 (555) 010-0177","role":"member"}'{"ok":true}
2026/10/09 08:42:19 sms to=+15550100177
You were invited to join an organization. Sign in with this address, verify it if you have not, and accept the invitation here:
http://localhost:8081/invitations
Carol signs up with her email, adds the number (POST /auth/phone/add), verifies it with the texted code (POST /auth/phone/verify), and only then does GET /auth/organization/invites list the invitation, with "kind":"phone","identifier":"+15550100177". Check: TestOrgTeams_TeamsRolesAndInvites in examples/org-teams.
An app that adds members only from the server (org.AddMember) passes organization.WithoutInvitations(): the invitation routes are not mounted, and no identifier plugin, BaseURL or InviteLink is needed.
Bob signs up with the invited address. His list of invitations, GET /auth/organization/invites, is empty until he verifies it, because anyone can type any address at sign-up; the invitation is matched against the identities the user has verified, exactly, on the normalized value.
curl -s -c bob.txt -X POST localhost:8081/auth/password/sign-up -H "$O" \
-d '{"identifier":"bob@example.com","password":"correct horse battery staple","name":"Bob"}'
curl -s -b bob.txt localhost:8081/auth/organization/invites
curl -s -b bob.txt -X POST localhost:8081/auth/email/verify -H "$O" -d '{"token":"<token from the mailed link>"}'
curl -s -b bob.txt localhost:8081/auth/organization/invites{"user":{"id":"usr_ruqwnkq3nklnfdhqjrdmtbfd","name":"Bob","image":""},"verificationRequired":false,"secondFactorRequired":false}
{"invites":[]}
{"email":"bob@example.com"}
{"invites":[{"id":"inv_vpe2ps24ob223xsawzo4ranh","orgId":"org_7n2gshuichmdexqwfljzp56x","orgName":"Acme","email":"bob@example.com","role":"member","expiresAt":"2026-10-08T05:19:20.498563Z"}]}Carol, signed in with a different verified address, cannot accept Bob's invitation by its id. Bob accepts once; the second time it is gone:
curl -s -b carol.txt -X POST localhost:8081/auth/organization/accept -H "$O" -d '{"inviteId":"inv_vpe2ps24ob223xsawzo4ranh"}'
curl -s -b bob.txt -X POST localhost:8081/auth/organization/accept -H "$O" -d '{"inviteId":"inv_vpe2ps24ob223xsawzo4ranh"}'
curl -s -b bob.txt -X POST localhost:8081/auth/organization/accept -H "$O" -d '{"inviteId":"inv_vpe2ps24ob223xsawzo4ranh"}'
curl -s -b bob.txt localhost:8081/auth/organization/list{"error":{"code":"organization.invite_invalid","message":"This invitation is not valid any more."}}
{"id":"org_7n2gshuichmdexqwfljzp56x","slug":"acme","name":"Acme","createdAt":"2026-10-01T05:19:20.39302Z"}
{"error":{"code":"organization.invite_invalid","message":"This invitation is not valid any more."}}
{"orgs":[{"id":"org_7n2gshuichmdexqwfljzp56x","slug":"acme","name":"Acme","createdAt":"2026-10-01T05:19:20.39302Z","role":"member"}]}Accepting as someone who is already a member changes nothing: an invitation never promotes or demotes. Invitations expire after a week (organization.WithInviteTTL changes it); auth sweep deletes expired unaccepted ones through the plugin's Sweep, together with the active-organization selections of expired sessions, and accepted ones stay as a record of who invited whom.
Plugin.Sweep · plugin/organization/organization.go:2588-2597
func (p *Plugin) Sweep(ctx context.Context, cutoff time.Time) (int64, error) {
q := sqlb.NewDelete(p.core.Dialect()).From(TableInvite).
Where(sqlb.Less(InviteExpiresAt, cutoff), sqlb.IsNull(InviteAccepted))
n, err := p.core.Exec(ctx, q)
if err != nil {
return n, err
}
m, err := p.core.Exec(ctx, sqlb.NewDelete(p.core.Dialect()).From(TableActive).Where(sqlb.LessEq(ActiveExpiresAt, cutoff)))
return n + m, err
}Every operation checks a permission, resource:action, against the caller's roles; the built-in roles grant these defaults (organization.DefaultRoles):
| Role | Permissions | In words |
|---|---|---|
owner |
every statement of organization.DefaultStatements |
Everything, including deleting the organization. Only an owner may grant the owner role or change or remove an owner, and the last owner can neither leave nor be demoted |
admin |
organization:update, member:create/update/delete, invitation:create/cancel, team:create/update/delete, ac:create/read/update/delete |
Run the organization except deleting it or touching owners |
member |
ac:read |
List members and teams; leave |
Every member may read the organization, its members and its invitations, and leave. A member holding several roles ("admin,billing", or ["admin","billing"] in JSON) may do what any one of them allows. Role.AtLeast compares the built-in roles by rank, for code that only knows those three:
Role.AtLeast · plugin/organization/organization.go:251
func (r Role) AtLeast(need Role) bool { return r.Rank() >= need.Rank() }Alice lists the members; Carol, not a member, gets 404 organization.not_member, the same answer as for an organization that does not exist; Bob, a member, may not invite:
curl -s -b alice.txt 'localhost:8081/auth/organization/members?orgId=org_7n2gshuichmdexqwfljzp56x'
curl -s -b carol.txt 'localhost:8081/auth/organization/members?orgId=org_7n2gshuichmdexqwfljzp56x'
curl -s -b bob.txt -X POST localhost:8081/auth/organization/invite -H "$O" \
-d '{"orgId":"org_7n2gshuichmdexqwfljzp56x","email":"carol@example.com","role":"member"}'{"members":[{"user":{"id":"usr_m3mzjqnkozbyecm67f6evmxp","name":"Alice","image":""},"role":"owner","joinedAt":"2026-10-01T05:19:20.393135Z"},{"user":{"id":"usr_ruqwnkq3nklnfdhqjrdmtbfd","name":"Bob","image":""},"role":"member","joinedAt":"2026-10-01T05:19:24.933532Z"}]}
{"error":{"code":"organization.not_member","message":"Not found."}}
{"error":{"code":"organization.forbidden","message":"Your role does not allow this."}}Alice promotes Bob to admin with POST /auth/organization/set-role. He may now invite a member or an admin, but not an owner, and he may change the roles of members and admins but not make anyone an owner:
curl -s -b alice.txt -X POST localhost:8081/auth/organization/set-role -H "$O" \
-d '{"orgId":"org_7n2gshuichmdexqwfljzp56x","userId":"usr_ruqwnkq3nklnfdhqjrdmtbfd","role":"admin"}'
curl -s -b bob.txt -X POST localhost:8081/auth/organization/invite -H "$O" \
-d '{"orgId":"org_7n2gshuichmdexqwfljzp56x","email":"carol@example.com","role":"owner"}'
curl -s -b bob.txt -X POST localhost:8081/auth/organization/invite -H "$O" \
-d '{"orgId":"org_7n2gshuichmdexqwfljzp56x","email":"carol@example.com","role":"admin"}'
curl -s -b bob.txt -X POST localhost:8081/auth/organization/set-role -H "$O" \
-d '{"orgId":"org_7n2gshuichmdexqwfljzp56x","userId":"usr_ruqwnkq3nklnfdhqjrdmtbfd","role":"owner"}'{"ok":true}
{"error":{"code":"organization.forbidden","message":"Your role does not allow this."}}
{"ok":true}
{"error":{"code":"organization.forbidden","message":"Your role does not allow this."}}The last owner stays. Alice cannot demote herself or leave while she is the only owner; Bob, an admin, cannot remove her; Bob may leave:
curl -s -b alice.txt -X POST localhost:8081/auth/organization/set-role -H "$O" \
-d '{"orgId":"org_7n2gshuichmdexqwfljzp56x","userId":"usr_m3mzjqnkozbyecm67f6evmxp","role":"member"}'
curl -s -b alice.txt -X POST localhost:8081/auth/organization/remove-member -H "$O" -d '{"orgId":"org_7n2gshuichmdexqwfljzp56x","userId":"usr_m3mzjqnkozbyecm67f6evmxp"}'
curl -s -b bob.txt -X POST localhost:8081/auth/organization/remove-member -H "$O" -d '{"orgId":"org_7n2gshuichmdexqwfljzp56x","userId":"usr_m3mzjqnkozbyecm67f6evmxp"}'
curl -s -b bob.txt -X POST localhost:8081/auth/organization/remove-member -H "$O" -d '{"orgId":"org_7n2gshuichmdexqwfljzp56x","userId":"usr_ruqwnkq3nklnfdhqjrdmtbfd"}'
curl -s -b bob.txt localhost:8081/auth/organization/list{"error":{"code":"organization.last_owner","message":"An organization needs at least one owner."}}
{"error":{"code":"organization.last_owner","message":"An organization needs at least one owner."}}
{"error":{"code":"organization.forbidden","message":"Your role does not allow this."}}
{"ok":true}
{"orgs":[]}From Go: org.SetRole(ctx, organization.SetRoleRequest{…}), org.RemoveMember(ctx, organization.MemberRequest{…}), and org.RoleOf(ctx, orgID, userID) for your own checks, which returns organization.ErrNotMember for a non-member.
RequireRole is middleware for the app's routes. It takes a function that finds the organization in the request (a path value, a header, a subdomain) and the least role allowed, and it must sit inside authhttp.Middleware. A stranger gets 404, a lower role 403:
Plugin.RequireRole · plugin/organization/organization.go:2606-2621
func (p *Plugin) RequireRole(orgID func(r *http.Request) string, role Role) func(http.Handler) http.Handler {
return authhttp.RequireFunc(func(r *http.Request) error {
u, ok := auth.CurrentUser(r.Context())
if !ok {
return auth.ErrSignedOut
}
have, err := p.RoleOf(r.Context(), orgID(r), u.ID)
if err != nil {
return err
}
if !have.AtLeast(role) {
return ErrForbidden
}
return nil
})
}The example guards two pages, a dashboard for every member and billing for admins and owners:
newHandler · examples/organizations/main.go:139-150
func newHandler(a *auth.Auth) (http.Handler, error) {
orgs, err := auth.PluginOf[*organization.Plugin](a)
if err != nil {
return nil, err
}
mw := authhttp.Middleware(a)
mux := http.NewServeMux()
mux.Handle(authPrefix+"/", authhttp.Handler(a, authhttp.Prefix(authPrefix)))
mux.Handle("GET /orgs/{"+pathOrgParam+"}/dashboard", mw(orgs.RequireRole(orgInPath, organization.RoleMember)(page("dashboard"))))
mux.Handle("GET /orgs/{"+pathOrgParam+"}/billing", mw(orgs.RequireRole(orgInPath, organization.RoleAdmin)(page("billing"))))
return mux, nil
}orgInPath · examples/organizations/main.go:156
func orgInPath(r *http.Request) string { return r.PathValue(pathOrgParam) }From the example's own walkthrough, Bob as a member and Alice as the owner:
curl -s -b bob.txt localhost:8081/orgs/org_uthxqr3x3c4pgpfee2v6hs6m/dashboard
curl -s -b bob.txt localhost:8081/orgs/org_uthxqr3x3c4pgpfee2v6hs6m/billing
curl -s -b alice.txt localhost:8081/orgs/org_uthxqr3x3c4pgpfee2v6hs6m/billing
curl -s -b carol.txt localhost:8081/orgs/org_uthxqr3x3c4pgpfee2v6hs6m/dashboard{"page":"dashboard","orgId":"org_uthxqr3x3c4pgpfee2v6hs6m","user":"Bob"}
{"error":{"code":"organization.forbidden","message":"Your role does not allow this."}}
{"page":"billing","orgId":"org_uthxqr3x3c4pgpfee2v6hs6m","user":"Alice"}
{"error":{"code":"organization.not_member","message":"Not found."}}Everything of yours that belongs to a workspace references auth_org.id, the way a user's rows reference auth_user.id; reading and joining the plugin's tables is open to the app, writing them is not (the invariants live in the operations). The typed columns are exported (organization.OrgID, organization.MemberRole, …), so a query against them is checked at compile time.
To bring one organization's membership into a composite user query, join with UserJoin and bind with UserBindings. The join is LEFT, so a non-member still comes back, with an empty role and a nil JoinedAt:
UserJoin · plugin/organization/organization.go:2557-2566
func UserJoin(orgID string) sqlb.Join {
return sqlb.Join{
Type: sqlb.JoinLeft,
Table: TableMember,
On: []sqlb.Predicate{
sqlb.EqExpr(MemberUserID, auth.UserID),
sqlb.Eq(MemberOrgID, orgID),
},
}
}UserMembership · plugin/organization/organization.go:2523-2537
type UserMembership struct {
// Role is the user's role in the organization the join was parameterised
// with. Empty when they are not a member, because the join is LEFT and the
// binding coalesces the null away.
Role Role
// JoinedAt is nil when they are not a member.
//
// A pointer rather than a bare time.Time because this column arrives via a
// LEFT join and database/sql cannot scan NULL into a time.Time. Coalescing
// it would mean inventing a fallback timestamp, which is worse than nil: a
// zero time reads as a real value from 1 January year 1 and will eventually
// be formatted into someone's interface.
JoinedAt *time.Time
}UserBindings · plugin/organization/organization.go:2576-2581
func UserBindings(dst *UserMembership) []sqlb.Binding {
return []sqlb.Binding{
sqlb.Bind(sqlb.Coalesce(MemberRole, sqlb.Literal[Role]("''")), &dst.Role),
sqlb.Bind(sqlb.Nullable(MemberJoinedAt), &dst.JoinedAt),
}
}The org id is bound as a parameter inside the ON clause, never interpolated, so a value from the URL is safe to pass. See databases for the composite user itself.
Writing your own rows is where the transaction matters. An app table keyed by org_id (projects, billing, settings) should never disagree with auth_org: no organization without its first row, no rows left after the organization is deleted. examples/org-workspace keeps a project table that way, in two places.
Every organization, created over HTTP or from Go, gets its first project from an AfterCreateOrg hook, and BeforeDeleteOrg removes the projects. Hooks run inside the operation's transaction, and a.Conn(ctx) returns that transaction, so an error in either hook rolls the organization back too. The hooks need the *auth.Auth, which does not exist yet when the plugin's options are built, so they are passed with organization.WithHooksFrom(hooks): the plugin calls hooks(a) once, when auth.New initializes it.
hooks · examples/org-workspace/main.go:159-174
func hooks(a *auth.Auth) organization.Hooks {
return organization.Hooks{
AfterCreateOrg: func(ctx context.Context, org organization.Org, _ auth.User) error {
_, err := addProject(ctx, a, org.ID, defaultProject)
return err
},
BeforeDeleteOrg: func(ctx context.Context, org organization.Org) error {
conn, err := a.Conn(ctx)
if err != nil {
return err
}
_, err = conn.ExecContext(ctx, deleteProjects, org.ID)
return err
},
}
}When your code creates the organization itself (an import, a sign-up that also creates the company), wrap it in a.Tx. CreateFor joins the transaction, so a row of yours that cannot be written undoes the organization as well:
importWorkspace · examples/org-workspace/main.go:219-234
func importWorkspace(ctx context.Context, a *auth.Auth, orgs *organization.Plugin, in ImportRequest) (organization.Org, error) {
var org organization.Org
err := a.Tx(ctx, func(ctx context.Context, _ *sql.Tx) error {
var err error
if org, err = orgs.CreateFor(ctx, in.OwnerID, organization.CreateRequest{Name: in.Name, Slug: in.Slug}); err != nil {
return err
}
for _, name := range in.Projects {
if _, err := addProject(ctx, a, org.ID, name); err != nil {
return err
}
}
return nil
})
return org, err
}Try it: go test ./org-workspace in examples. TestOrgWorkspace_ImportIsAllOrNothing imports a workspace whose project collides with the default one and finds neither the organization nor any project afterwards; TestOrgWorkspace_DeleteTakesTheProjects deletes one organization over HTTP and keeps another's projects. The app's own routes over the table check the request's origin themselves (the library checks it only on its own routes), which the example's README shows with a real run:
{"orgId":"org_jzvh7nimq3wewbk76cqil6bq","projects":[{"id":"prj_kfkjxpw7wg7wxvegd4skpot5","name":"General"}]}
{"error":{"code":"project.name_taken","message":"A project with this name already exists."}}
{"error":{"code":"auth.origin_not_trusted","message":"This request came from a site that is not trusted."}}create also takes logo (a URL) and metadata (a JSON object of at most 16 KiB, organization.MaxMetadataSize), and both come back on every read of the organization. A member reads one organization with GET /auth/organization/get-organization?orgId= (or orgSlug=), and a settings page reads everything at once with GET /auth/organization/get-full-organization: the organization, its members (membersLimit, default 50), its pending invitations and, with teams on, its teams.
POST /auth/organization/update with {orgId, data: {name, slug, logo, metadata}} needs organization:update (owner, admin); a field left out stays, an empty logo clears it, and the slug follows the create rules. POST /auth/organization/delete with {orgId} needs organization:delete (owner only) and removes the organization with its members, invitations, teams, dynamic roles and every session's selection of it, in one transaction. From Go: org.Get, org.GetFull, org.Update, org.Delete.
Each session may have an active organization (activeOrganizationId). Creating an organization makes it active (send keepCurrentActiveOrganization: true to keep the current one); POST /auth/organization/set-active with {orgId} or {orgSlug} switches, for members only, and {} clears it. GET /auth/organization/active answers {activeOrganizationId, activeTeamId, organization}.
Every operation that takes an orgId uses the active organization when it is left out, so a frontend that has selected a workspace can call members, invite, list-invitations and the rest without repeating it; with neither, the answer is 400 organization.no_active. In your own handlers, org.ActiveOrgID(ctx) returns it.
The selection lives in auth_org_active, keyed by session id, not as a column of auth_session, so it works with every session store (SQL, Redis, memory, stateless). Signing out drops it, a pending second-factor session hands it to the full session, removing a member drops theirs, and auth sweep removes the selections of expired sessions. An API-key request has no session and gets 409 auth.session_data_unavailable from set-active.
An app route that scopes its own queries to the selection reads it from Go. The example's /workspace page answers the active organization and team:
workspace · examples/org-teams/main.go:181-199
func workspace(orgs *organization.Plugin) http.HandlerFunc {
return func(w http.ResponseWriter, r *http.Request) {
active, err := orgs.Active(r.Context())
if err != nil {
authhttp.WriteError(w, err)
return
}
if active.OrgID == nil {
authhttp.WriteError(w, errNoWorkspace)
return
}
out := workspaceResponse{OrgID: *active.OrgID}
if active.TeamID != nil {
out.TeamID = *active.TeamID
}
w.Header().Set("Content-Type", "application/json")
_ = json.NewEncoder(w).Encode(out) // a client that hung up cannot be told
}
}Right after Alice creates Acme, it is her active organization:
curl -s -b alice.txt localhost:8081/auth/organization/active
curl -s -b alice.txt localhost:8081/workspace{"activeOrganizationId":"org_cnovtgatzadaew2d5g6fmd4r","activeTeamId":null,"organization":{"id":"org_cnovtgatzadaew2d5g6fmd4r","slug":"acme","name":"Acme","createdAt":"2026-10-09T03:12:19.801789Z"}}
{"orgId":"org_cnovtgatzadaew2d5g6fmd4r"}Check: TestOrgTeams_TeamsRolesAndInvites (the selection after create, and after set-active-team).
An invitation is pending, accepted, rejected or canceled (organization.InviteStatusValues). The invitee declines with POST /auth/organization/reject-invitation {inviteId}, matched through the same verified address as accept. A member with invitation:cancel (owner, admin) withdraws one with POST /auth/organization/cancel-invitation {inviteId}; a stranger, an unknown id and an invitation that is no longer pending all get 404 organization.invite_invalid. GET /auth/organization/list-invitations?orgId= lists every invitation of the organization, newest first, with its status, inviter and team, for any member.
To send a pending invitation again, invite the same address with "resend": true: the invitation keeps its id, role and team, gets a fresh expiry and a new mail, and no second invitation is created. With nothing pending, resend is an ordinary invite. To make a plain second invite fail instead of adding another pending invitation, turn on organization.RefuseRepeatInvites(); the second invite is then 409 organization.already_invited.
An organization holds at most 100 pending invitations by default (organization.InvitationLimit(n); 0 is no cap); one more is 409 organization.invitation_limit. Inviting an existing member is allowed by default and accepting keeps their role; organization.RejectExistingMembers() refuses it with 409 organization.already_member, and refuses AddMember of a member too.
POST /auth/organization/has-permission with {orgId, permissions: {"member": ["delete"]}, connector} answers {"success": true|false} for the caller; connector is AND (default) or OR across resources. On the server, org.Can(ctx, orgID, userID, access.Request{…}, access.And) answers the same, and RequirePermission guards a route the way RequireRole does:
ExamplePlugin_RequirePermission · plugin/organization/example_test.go:29-38
func ExamplePlugin_RequirePermission() {
orgs := organization.New()
orgInPath := func(r *http.Request) string { return r.PathValue("org") }
createProject := http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) { w.WriteHeader(http.StatusCreated) })
mux := http.NewServeMux()
// Inside authhttp.Middleware in a real app.
mux.Handle("POST /orgs/{org}/projects", orgs.RequirePermission(orgInPath, access.Request{"project": access.All("create")})(createProject))
fmt.Println("mounted")
// Output: mounted
}To add resources of your own, build an access control from a copy of organization.DefaultStatements plus yours, and roles from it, with the access module:
ExampleWithRoles · plugin/organization/example_test.go:14-24
func ExampleWithRoles() {
s := access.Statements{"project": {"create", "share"}}
for k, v := range organization.DefaultStatements {
s[k] = v
}
ac := access.MustNew(s)
billing := ac.MustRole(access.Permissions{"project": {"create"}, organization.ResourceInvitation: {organization.ActionCreate}})
org := organization.New(organization.WithAccessControl(ac), organization.WithRoles(map[organization.Role]access.Role{"billing": billing}))
fmt.Println(org.Name(), billing.Allows(access.Request{"project": access.All("create")}))
// Output: organization true
}WithRoles adds roles and replaces a built-in one given under its name; auth.New refuses a role that names a statement the access control does not declare. organization.CreatorRole(r) makes the creator admin, say, instead of owner; it is also the role the owner protections guard. TestR30_PermissionsAndCustomRoles in integration/r30_test.go runs this setup on all three engines.
A model other than roles. Every permission decision above (each operation's check, has-permission, Can, RequirePermission, the grant check of a dynamic role, and plugin/apikey's organization-key question) goes through one organization.Authorizer, and organization.WithAuthorizer(a) replaces the role check with yours: attributes, a relationship store, a policy engine. It receives an organization.AccessRequest (organization, user, the member's role, the access.Request, the connector, the operation and the call) and any error refuses. Membership stays the plugin's, so a non-member is refused before it is asked, and roles keep deciding which roles a member may be given and the owner protections. To keep the roles and add a rule, wrap org.RoleAuthorizer(). Under a custom authorizer the creator role's all-permissions shortcut for organization API keys is off: the authorizer decides those keys too. Bring your own authorization builds one on a relationship store.
organization.Teams(organization.TeamsConfig{…}) turns on teams, sub-groups inside an organization. Every new organization gets a default team named after it, with the creator in it (NoDefaultTeam turns that off, DefaultTeamName names it).
The org-teams example turns on teams, run-time roles, hooks and invitations by email or phone in one place; its limits are named constants of the app:
newAuth · examples/org-teams/main.go:115-131
func newAuth(db *sql.DB, m email.Mailer, sms phone.SMSSender, joined func(organization.MemberChange)) (*auth.Auth, error) {
return auth.New(
auth.WithDB(db, sqlb.SQLiteDialect{}),
auth.WithBaseURL(baseURL),
auth.WithPlugins(
email.New(email.Login(), email.Recover(), email.WithMailer(m)),
phone.New(phone.WithSMS(sms)),
password.New(),
organization.New(
organization.Teams(organization.TeamsConfig{MaxTeams: maxTeams, MaxMembersPerTeam: maxMembersPerTeam}),
organization.DynamicRoles(organization.DynamicRolesConfig{MaxRoles: maxCustomRoles}),
organization.InviteBy(email.KindEmail, phone.KindPhone),
organization.WithHooks(hooks(joined)),
),
),
)
}Acme has its default team as soon as it exists, and Alice adds one; orgId is left out, so the active organization is used:
curl -s -b alice.txt localhost:8081/auth/organization/list-teams
curl -s -b alice.txt -X POST localhost:8081/auth/organization/create-team -H 'Origin: http://localhost:8081' -d '{"name":"Design"}'{"teams":[{"id":"team_l4gxddx374afpejp3qxeb3lo","orgId":"org_cnovtgatzadaew2d5g6fmd4r","name":"Acme","createdAt":"2026-10-09T03:12:19.801889Z","updatedAt":"2026-10-09T03:12:19.801889Z","memberCount":1}]}
{"id":"team_y3ckjx5vzmybhohh7ltuyeov","orgId":"org_cnovtgatzadaew2d5g6fmd4r","name":"Design","createdAt":"2026-10-09T03:12:19.83225Z","updatedAt":"2026-10-09T03:12:19.83225Z","memberCount":0}| Route | Needs |
|---|---|
POST /auth/organization/create-team {orgId, name} |
team:create; at most MaxTeams per organization (409 organization.teams_limit) |
GET /auth/organization/list-teams?orgId= |
membership; each team carries memberCount |
POST /auth/organization/update-team {teamId, data: {name}} |
team:update |
POST /auth/organization/remove-team {teamId} |
team:delete; the last team stays (409 organization.last_team) unless AllowRemovingAllTeams |
POST /auth/organization/add-team-member {teamId, userId} |
team:update; the user must be a member of the organization; at most MaxMembersPerTeam (409 organization.team_members_limit) |
POST /auth/organization/remove-team-member {teamId, userId} |
yourself, or team:update |
POST /auth/organization/set-active-team {teamId} |
being in the team; it also makes its organization active. {} clears the team and keeps the organization |
GET /auth/organization/list-user-teams |
signed in: the caller's teams in every organization |
GET /auth/organization/list-team-members?teamId= |
membership of the team's organization; without teamId, the session's active team (400 organization.no_active_team when there is none) |
A team of an organization the caller is not in answers 404 organization.team_not_found, like an unknown one. An invitation may carry teamId, and accepting it joins that team too. Leaving or being removed from the organization removes the member from its teams; deleting a team clears it from the sessions that had it active.
In the example Bob is invited with "teamId" set to Design, so accepting puts him in it (list-user-teams answers that one team), and Carol chooses Design with set-active-team, after which /workspace answers both ids. Check: TestOrgTeams_TeamsRolesAndInvites.
organization.DynamicRoles(organization.DynamicRolesConfig{MaxRoles: n}) lets each organization define roles of its own, stored in auth_org_role (dynamic access control):
| Route | Needs |
|---|---|
POST /auth/organization/create-role {orgId, role, permission} |
ac:create, and holding every permission the role grants: nobody mints a role stronger than their own |
POST /auth/organization/update-role {orgId, roleId or roleName, data: {roleName, permission}} |
ac:update; renaming only while no member holds the role |
POST /auth/organization/delete-role {orgId, roleId or roleName} |
ac:delete; refused while a member holds it (409 organization.role_in_use) |
GET /auth/organization/get-role, GET /auth/organization/list-roles |
ac:read (every built-in role has it) |
update-role and delete-role naming a configured role (owner, admin, member, or one from WithRoles) answer 400 organization.predefined_role: those change only with a deploy.
A dynamic role is assigned like any other (set-role, invite), and its permissions count in every check. Its name may not be a static role's (409 organization.role_taken), a permission outside the statements is 400 organization.bad_permission, and an organization holds at most MaxRoles (409 organization.roles_limit).
Alice gives Acme a designer role that may add and remove team members and nothing else, then invites Bob with it:
curl -s -b alice.txt -X POST localhost:8081/auth/organization/create-role -H 'Origin: http://localhost:8081' \
-d '{"role":"designer","permission":{"team":["update"]}}'{"id":"role_rqhepmdzzbbbiiqqj3pikous","orgId":"org_cnovtgatzadaew2d5g6fmd4r","role":"designer","permission":{"team":["update"]},"createdAt":"2026-10-09T03:12:19.855628Z","updatedAt":"2026-10-09T03:12:19.855628Z"}As a designer Bob adds Carol to Design, and his create-team is 403 organization.forbidden; while he holds the role, delete-role is 409 organization.role_in_use. Check: TestOrgTeams_TeamsRolesAndInvites and TestOrgTeams_ErrorsUndoTheOperation.
organization.WithHooks(organization.Hooks{…}) takes organization hooks as typed Go functions: Before/After for creating, updating and deleting an organization; adding, removing and re-roling a member; creating, accepting, rejecting and canceling an invitation; creating, updating and deleting a team; adding and removing a team member. They run inside the operation's transaction: a Before hook may change the row it gets as a pointer (rename the organization, set the invitation's expiry or role) or refuse with an error, and an After hook's error rolls the whole operation back. A hook that writes your own rows needs the *auth.Auth for a.Conn(ctx) (the operation's transaction) or a.Exec: pass organization.WithHooksFrom(func(a *auth.Auth) organization.Hooks {…}) instead, which the plugin calls with it at start-up; auth.New refuses both options together. What a hook changes is checked again, and the ids and the invited address are restored, so a hook can shape a row but never move it past a permission check. auth.OperationHook still works on every operation id for logging and vetoes.
The example refuses one team name its UI keeps for itself, with an error of its own, and reports every new member:
hooks · examples/org-teams/main.go:139-152
func hooks(joined func(organization.MemberChange)) organization.Hooks {
return organization.Hooks{
BeforeCreateTeam: func(_ context.Context, team *organization.Team) error {
if strings.EqualFold(strings.TrimSpace(team.Name), reservedTeamName) {
return ErrReservedTeamName
}
return nil
},
AfterAddMember: func(_ context.Context, m organization.MemberChange) error {
joined(m)
return nil
},
}
}The app's error reaches the client with its own code and status, and the refused team is not created:
curl -s -b alice.txt -X POST localhost:8081/auth/organization/create-team -H 'Origin: http://localhost:8081' -d '{"name":"Everyone"}'{"error":{"code":"app.team_name_reserved","message":"That team name is reserved."}}Check: TestOrgTeams_ErrorsUndoTheOperation (the refusal leaves one team) and TestOrgTeams_TeamsRolesAndInvites (the hook saw Bob join as designer and Carol as member). Declare the error once at package level with auth.NewError, as the example does, so its code is registered once and the client can match it.
organization.WithFields(organization.FieldsConfig{Org: …, Member: …, Invitation: …, Team: …, Role: …}) adds columns of your own, each an organization.Field{Name, Type, Nullable, Default, Required, ServerOnly} with the core's column types (auth.ColumnText, ColumnInt, ColumnBool, ColumnTimestamp). Each field is one migration (0006_field_<table>_<name>), so declaring one later migrates then; a NOT NULL field needs a constant Default.
Requests carry the values in a fields object ({"name":"Acme","slug":"acme","fields":{"seats":12}}) or as top-level keys beside the request's own ({"name":"Acme","slug":"acme","seats":12}; inside data for an update), on create and update of an organization, team and dynamic role and on invite. A field sent both ways is 400 auth.field_invalid, and a top-level key that is no field 400 auth.bad_request. Every read returns them in fields, defaults included. A value must have the column's type (a number for an int, an RFC 3339 string for a timestamp, null only for a nullable field) and the name must be declared, or the answer is 400 auth.field_invalid, which names neither. Required refuses a create without the field; ServerOnly refuses it from a client, so only Go calls and the Before hooks set it (a plan, an external id). Member fields are set from Go with org.AddMemberWith(ctx, organization.AddMemberRequest{…, Fields}) or by BeforeAddMember; a member field cannot be Required, because a member joins by an invitation that carries none. auth.New refuses a name that is not a plain identifier or shadows a column, an unknown type, a default that is not a constant literal, and team or role fields without Teams or DynamicRoles. TestR30_AdditionalFields runs every table on the three engines.
organization.Domains(organization.DomainsConfig{…}) lets an organization claim its email domain (Clerk's verified domains). An admin adds acme.com, proves the organization owns it, and picks what happens to anyone whose address at acme.com becomes verified:
enrollmentMode |
What the user gets |
|---|---|
manual_invitation (default) |
Nothing; invite people by hand as before |
automatic_invitation |
A pending invitation in GET /auth/organization/invites, accepted like any other; no mail is sent, since the user is in the app verifying right now |
automatic_suggestion |
The organization in GET /auth/organization/domain-suggestions; accept-suggestion asks to join, and an admin approves with approve-membership-request (or reject-membership-request, after which it is not suggested again) |
automatic_join |
Membership with the domain's role (member by default) |
Only a VERIFIED address enrolls: the plugin listens for an email identity being created verified or having its verified_at set, so typing bob@acme.com into a sign-up form does nothing until Bob clicks the link. Only a PROVED domain enrolls: a claim alone does nothing, so several organizations may claim acme.com, and the first to prove it gets it; after that nobody else can add it. A domain never grants the creator role, public mail domains (gmail.com and the rest of organization.DefaultPublicDomains) are refused, and adding, verifying, changing and removing a domain needs organization:update.
The org-domains example wires it:
newAuth · examples/org-domains/main.go:98-111
func newAuth(db *sql.DB, m email.Mailer, verifier organization.DomainVerifier) (*auth.Auth, error) {
return auth.New(
auth.WithDB(db, sqlb.SQLiteDialect{}),
auth.WithBaseURL(baseURL),
auth.WithPlugins(
email.New(email.Login(), email.Recover(), email.WithMailer(m)),
password.New(),
organization.New(organization.Domains(organization.DomainsConfig{
Verifier: verifier,
TrustVerifiedEmail: true,
})),
),
)
}Proof is a DNS TXT record by default: add-domain answers the recordName and recordValue to publish, and verify-domain looks it up (at most 10 times a minute per client address). Replace the check with your own DomainVerifier (an HTTP file, your registrar's API, a fake in tests); its error answers 503 organization.domain_check_failed, never a pass. With TrustVerifiedEmail, as in the example, an admin who has a verified address at the domain proves it by adding it. That is off by default because it lets any employee with a work address claim the company's domain for an organization they made; DNS needs control of the zone. From Go, org.MarkDomainVerified(ctx, domainID) verifies one an operator checked another way.
Alice, with a verified alice@acme.com, adds acme.com in auto-join mode; gmail.com is refused:
curl -s -b alice.txt -X POST localhost:8081/auth/organization/add-domain -H 'Origin: http://localhost:8081' \
-d '{"orgId":"org_2ms64etgftxzv7ummx3vlsqe","domain":"acme.com","enrollmentMode":"automatic_join","role":"member"}'
curl -s -b alice.txt -X POST localhost:8081/auth/organization/add-domain -H 'Origin: http://localhost:8081' \
-d '{"orgId":"org_2ms64etgftxzv7ummx3vlsqe","domain":"gmail.com"}'{"id":"odom_sky2r55agi7eqwzzlxe3jqv2","orgId":"org_2ms64etgftxzv7ummx3vlsqe","domain":"acme.com","enrollmentMode":"automatic_join","role":"member","verified":true,"verifiedAt":"2026-10-13T12:40:09.662605Z","recordName":"_auth-verification.acme.com","recordValue":"auth-domain-verification=svIv7ocaELO3T1vfV7dyC8X6MkHaJ2cZf3YDLfI94CU","createdAt":"2026-10-13T12:40:09.662482Z"}
{"error":{"code":"organization.public_domain","message":"This is a public email domain and cannot belong to an organization."}}Bob signs up with bob@acme.com. He is in no organization until he verifies the address, and in Acme right after:
curl -s -b bob.txt localhost:8081/auth/organization/list
curl -s -b bob.txt -X POST localhost:8081/auth/email/verify -H 'Origin: http://localhost:8081' -d '{"token":"…"}'
curl -s -b bob.txt localhost:8081/auth/organization/list{"orgs":[]}
{"email":"bob@acme.com"}
{"orgs":[{"id":"org_2ms64etgftxzv7ummx3vlsqe","slug":"acme","name":"Acme","createdAt":"2026-10-13T12:40:09.649952Z","role":"member"}]}People who verified an acme.com address before the domain was proved are not enrolled retroactively; suggestions are worked out when listed, so they do see those. Enrollment that the organization's own rules refuse (MaxMembers, a BeforeAddMember hook) is logged and skipped rather than failing the user's verification. Removing a domain drops its pending requests; invitations it created stay until canceled or expired.
| Option | What it does | Default |
|---|---|---|
organization.WithInviteTTL(d) |
How long an invitation stays acceptable | a week (organization.DefaultInviteTTL) |
organization.InviteLink(func() string) |
The page the mail links to; called per mail | BaseURL + /invitations |
organization.InviteBy(kinds...) |
The identifier kinds an invitation may be addressed to, such as phone.KindPhone; the first is used when a request names no kind |
|
organization.WithoutInvitations() |
No invitation routes; members are added from Go only (AddMember). Requires no identifier plugin |
invitations on |
organization.InviteMessage(func(organization.InviteMail) (subject, text string)) |
Word the mail yourself from the invitation, the organization, the inviter and the link ("Alice invited you to Acme") | the plugin's wording |
email.Templates(fn) on the email plugin |
Your own wording for organization.PurposeInvite, which wins over InviteMessage; m.Data.(organization.InvitationData) gives it the invitation's fields |
the plugin's wording |
organization.InviteLimit(n, window) |
How many invitations one client address may send per window | 50 per hour |
organization.ReplacePendingInvites() |
Inviting an address again withdraws its pending invitations to that organization and sends one fresh mail | off: each invite adds a pending invitation |
organization.RefuseRepeatInvites() |
Inviting an address that already has a pending invitation is 409 organization.already_invited, unless the request sets resend |
off: each invite adds a pending invitation |
organization.CreateGate(func(ctx, auth.User) (bool, error)) |
Who may create an organization, for example only on a paid plan; false answers 403 organization.create_forbidden |
everyone signed in |
organization.MaxOwned(n) |
How many organizations one user may own; the next create is 409 organization.limit_reached |
no cap |
organization.MaxMembers(n) |
How many members an organization may have; accepting or AddMember into a full one is 409 organization.members_limit, invitations still go out |
no cap |
organization.InvitationLimit(n) |
Pending invitations one organization may hold; 0 is no cap |
100 |
organization.RejectExistingMembers() |
Refuse to invite or add someone already in the organization | off: the invitation goes out and accepting keeps the role |
organization.CreatorRole(r) |
The role the creator gets, and the one the owner protections guard | owner |
organization.WithAccessControl(ac), organization.WithRoles(map) |
Your permission vocabulary and roles (Step 11) | DefaultStatements, DefaultRoles() |
organization.Teams(organization.TeamsConfig{…}) |
Teams (Step 12): MaxTeams, MaxMembersPerTeam, AllowRemovingAllTeams, NoDefaultTeam, DefaultTeamName |
off |
organization.DynamicRoles(organization.DynamicRolesConfig{MaxRoles: n}) |
Roles created per organization at run time (Step 13) | off |
organization.Domains(organization.DomainsConfig{…}) |
Verified domains (Step 16): Verifier, RecordPrefix, TrustVerifiedEmail, IsPublicDomain, MaxDomains |
off |
organization.WithHooks(organization.Hooks{…}) |
Lifecycle hooks (Step 14) | none |
organization.WithHooksFrom(func(a *auth.Auth) organization.Hooks) |
The same hooks, built once at start-up with the *auth.Auth, for hooks that write through a.Conn(ctx); not with WithHooks |
none |
organization.WithFields(organization.FieldsConfig{…}) |
Extra columns on the plugin's tables (Step 15) | none |
Three more reads help a frontend: GET /auth/organization/check-slug?slug= answers {slug, available} before the create form submits; GET /auth/organization/role?orgId= is the caller's own role; GET /auth/organization/invite?inviteId= is one of the caller's pending invitations, for an accept page. members takes page and limit (default 50, at most 200) and returns total, and orders and narrows with sortBy (joinedAt or its other name createdAt, name, role, userId), sortDirection (asc, desc), filterField, filterOperator and filterValue: on role, userId and name the operators eq, ne, in and not_in (comma-separated values), contains, starts_with and ends_with, which keep case on every engine; on joinedAt or createdAt an RFC 3339 time with eq, ne, lt, lte, gt and gte ("members who joined after the first of October"); anything else is 400 organization.bad_query; remove-member takes email instead of userId for a page that lists addresses, or kind and identifier for any other verified identifier.
From Go only, for a seed or an import: org.CreateFor(ctx, userID, organization.CreateRequest{…}) creates an organization owned by a user without the gate or the cap, and org.AddMember(ctx, orgID, userID, role) adds a member without an invitation (an existing member keeps their role; MaxMembers and the hooks apply). Each runs in one transaction, joining the caller's when there is one.
For an operator's own admin screen, over every organization of the app: org.ListAll(ctx, organization.AllOrgsRequest{Page, Limit, Search}) pages through all organizations with their member counts, and GetFor, UpdateFor, DeleteFor, MembersFor, SetRoleFor, RemoveMemberFor, InvitationsFor and CancelFor act on any one of them. They check no session or membership, so put them behind your admin check (the admin plugin's RequireAdmin, for example); the last owner still cannot be demoted or removed, and the hooks run.
The /invitations page is yours to build: it lists GET /auth/organization/invites and posts the chosen id to accept.
github.com/ubgo/auth/plugin/organization/orgtest creates organizations, saves them and adds members for an authtest.Env whose Auth has this plugin: f := orgtest.New(env), then fix := f.NewOrganization(ownerID, "") builds one in memory (orgtest.DefaultOrgName, a random slug), fix.Members lists who else joins, and f.SaveOrganization(fix) writes it through CreateFor and AddMember, so every rule and hook runs. f.AddMember(orgID, userID, role) adds one more. Any refusal fails the test. It lives in this module because the core's authtest cannot import the plugin, and like authtest it imports no database driver.
examples/org-workspace builds its organizations this way. The fixtures go through CreateFor and AddMember, so the example's create hook gives a fixture organization its default project, exactly as the HTTP route does:
TestOrgWorkspace_RolesGuardTheData · examples/org-workspace/main_test.go:121-148
func TestOrgWorkspace_RolesGuardTheData(t *testing.T) {
a := newApp(t)
alice, bob, eve := a.env.CreateUser("Alice"), a.env.CreateUser("Bob"), a.env.CreateUser("Eve")
fix := a.f.NewOrganization(alice.ID, "Acme")
fix.Members = []orgtest.Member{{UserID: bob.ID, Role: organization.RoleMember}}
org := a.f.SaveOrganization(fix)
asBob := a.env.Browser(a.h)
asBob.SetSession(a.env.SignIn(bob.ID))
var list listResponse
asBob.Get("/orgs/" + org.ID + "/projects").Expect(http.StatusOK).Decode(&list)
if len(list.Projects) != 1 || list.Projects[0].Name != defaultProject {
t.Fatalf("a fixture organization's projects = %+v", list.Projects)
}
if code := asBob.Post("/orgs/"+org.ID+"/projects", createRequest{Name: "Roadmap"}).Expect(http.StatusForbidden).ErrorCode(); code != organization.ErrForbidden.Code {
t.Fatalf("a member creating: %q", code)
}
asEve := a.env.Browser(a.h)
asEve.SetSession(a.env.SignIn(eve.ID))
if code := asEve.Get("/orgs/" + org.ID + "/projects").Expect(http.StatusNotFound).ErrorCode(); code != organization.ErrNotMember.Code {
t.Fatalf("a stranger reading: %q", code)
}
// Adding Eve as an admin with the fixture lets her create.
a.f.AddMember(org.ID, eve.ID, organization.RoleAdmin)
asEve.Post("/orgs/"+org.ID+"/projects", createRequest{Name: "Roadmap"}).Expect(http.StatusCreated)
}Use this when the workspace switcher, the members page and the invitations page run in a browser or an app. The typed client has every route of this guide on client.organization; list organization() in plugins. Creating an organization, inviting, listing and switching are in Flows › Organizations; the blocks here are the pages after that.
The page the invitation mail links to (Step 4) lists the invitations for the user's verified addresses and accepts them by id:
acceptAllInvitations · clients/ts/examples/plugin-organization.ts:14-22
export async function acceptAllInvitations(): Promise<string[]> {
const { data } = await auth.organization.invites();
const joined: string[] = [];
for (const invitation of data?.invites ?? []) {
const { data: org, error } = await auth.organization.accept({ inviteId: invitation.id });
if (!error) joined.push(`${org.name} as ${invitation.role}`);
}
return joined;
}Members and a role change:
promote · clients/ts/examples/plugin-organization.ts:27-33
export async function promote(orgId: string, userId: string): Promise<string> {
const { data } = await auth.organization.members({ orgId, limit: "100" });
if (!(data?.members ?? []).some((m) => m.user.id === userId)) return "Not a member.";
const { error } = await auth.organization.setRole({ orgId, userId, role: "admin" });
if (!error) return "Promoted.";
return error.code === "organization.forbidden" ? "Only an owner or admin can change roles." : error.message;
}A permission check to hide a button the caller could not use (Step 11's vocabulary):
canInvite · clients/ts/examples/plugin-organization.ts:38-41
export async function canInvite(orgId: string): Promise<boolean> {
const { data } = await auth.organization.hasPermission({ orgId, permissions: { invitation: ["create"] } });
return data?.success ?? false;
}The active organization (Step 9) and teams (Step 12):
switchTo · clients/ts/examples/plugin-organization.ts:46-51
export async function switchTo(slug: string): Promise<string | null> {
const switched = await auth.organization.setActive({ orgSlug: slug });
if (switched.error) return null; // organization.not_member
const { data } = await auth.organization.active();
return data?.organization?.name ?? null;
}teamWith · clients/ts/examples/plugin-organization.ts:55-60
export async function teamWith(orgId: string, name: string, userId: string): Promise<string | null> {
const team = await auth.organization.createTeam({ orgId, name });
if (team.error) return null;
const added = await auth.organization.addTeamMember({ teamId: team.data.id, userId });
return added.error ? null : team.data.id;
}The codes a frontend handles, explained in What can go wrong: organization.forbidden (the caller's role does not allow it), organization.not_member, organization.slug_taken (check first with checkSlug), organization.bad_slug, organization.bad_role, organization.last_owner, organization.already_member, organization.already_invited, organization.invite_invalid, organization.limit_reached and the other *_limit codes, organization.no_active when a call relies on an active organization that is not set.
Try it: examples/ts-client-flows creates an organization, invites a colleague (who gets a mail), lists the caller's organizations with their role and makes one active, from Node (Flows › Try it).
Pitfalls:
- An invitation is accepted only by a verified address. A user who signed up with the invited address but has not verified it sees no invitations; send them to verify first.
orgIdis optional wherever the server falls back to the active organization.setActivetakesorgIdororgSlug(neither clears the selection),removeMembertakesuserId,emailorkindwithidentifier,updateRoletakesroleIdorroleName; send the one you have. Operations on an organization (invite,removeMember,setRole,hasPermission,createTeam,update,createRole,updateRole) act on the session's active organization whenorgIdis left out, and answerorganization.no_activewhen there is none.- Paging and filter inputs of list routes are strings (
members({ orgId, limit: "100" })), because they travel in the query string. - Teams and dynamic roles exist only when the server enables them (
Teams(),DynamicRoles()); the prebuilt client has their methods because it was generated with both, and a server without them answersauth.unknown_operation.
Every method with its route and types: TypeScript client reference › organization.
auth: plugin dependency not registered: "organization" requires "email"— the email plugin is missing fromauth.WithPlugins. Add it, or invite by another kind (organization.InviteBy) or not at all (organization.WithoutInvitations).auth: plugin "organization": organization: invitations are addressed by "phone", which no plugin registers—InviteBynames a kind whose identifier plugin is not inauth.WithPlugins.auth: plugin "organization": organization: invitations are addressed by "username", whose plugin cannot deliver messages: auth: the identifier kind's plugin cannot deliver messages—InviteBynames a kind nobody can send an invitation to; address invitations by email or phone instead.auth: plugin "organization": organization: invitation links need auth.WithBaseURL or organization.InviteLink— no page for the mail to link to.400 organization.bad_slug("Use lowercase letters, digits and dashes.") — the slug does not match the pattern above.409 organization.slug_taken("This address is already in use.") — another organization has the slug.400 organization.bad_role("This role does not exist.") — a role that is neither a static role (built-in orWithRoles) nor a dynamic role of the organization.404 organization.not_member("Not found.") — the caller, or the target of remove-member or set-role, is not a member. Also what a stranger sees fromRequireRole.403 organization.forbidden("Your role does not allow this.") — the caller's roles lack the permission the operation checks (a member inviting, an admin deleting the organization), a non-owner granting the owner role or touching an owner, or a role below the oneRequireRoleasks for, or a permissionRequirePermissionasks for.409 organization.last_owner("An organization needs at least one owner.") — demoting or removing the only owner. Make someone else an owner first.404 organization.invite_invalid("This invitation is not valid any more.") — the id is unknown, expired, already accepted, or addressed to an address the caller has not verified. One error for all four, so a guessed id reveals nothing.429 auth.rate_limitedoninvite— more than 50 invitations in an hour from one address, or whateverorganization.InviteLimitset.403 organization.create_forbidden("You cannot create an organization.") — theCreateGatesaid no for this user.409 organization.limit_reached("You have reached the number of organizations you can own.") —MaxOwned; promote someone else to owner and leave, or raise the cap.409 organization.members_limit("This organization is full.") —MaxMembers; the invitation stays pending until there is room.auth: plugin "organization": organization: InviteLimit needs a positive limit and window—InviteLimitwith a zero limit or window.400 organization.no_active("No organization is active.") — the request left outorgIdand its session has no active organization (Step 9).400 organization.bad_metadata— metadata that is not a JSON object, or over 16 KiB.400 organization.bad_query— a members sort or filter outside the lists above.409 organization.invitation_limit,409 organization.already_member— Step 10.404 organization.team_not_found,409 organization.teams_limit,409 organization.team_members_limit,409 organization.last_team— Step 12.404 organization.role_not_found,409 organization.role_taken,409 organization.roles_limit,409 organization.role_in_use,400 organization.bad_permission— Step 13.400 organization.bad_domain,400 organization.public_domain,409 organization.domain_taken,409 organization.domains_limit,409 organization.domain_not_verified,503 organization.domain_check_failed,400 organization.bad_enrollment,400 organization.domain_role,404 organization.domain_not_found,404 organization.request_invalid— Step 16.- A colleague at the domain was not enrolled — their address is not verified yet, the domain is not verified (
verified: falseinlist-domains), the mode ismanual_invitation, or they verified before the domain was proved (they still see it as a suggestion in suggestion mode). auth: plugin "organization": organization: CreatorRole "…" is not a static role,organization: role "…": access: unknown resource …— a creator role or aWithRolesrole that does not fit the access control.- A hook's own error — a
BeforeorAfterhook returned it, and the whole operation was rolled back. An*auth.Errorkeeps its code and status (400 app.team_name_reservedin the example); any other error is answered500 auth.internalwith no detail, so give a refusal the client should see anauth.NewErrorcode. - The invited user sees no invitation — their address is not verified yet, or it differs from the invited one after normalization. Verification first, then the list fills.
- Bring your own authorization: decide every organization permission with your own model;
examples/authorizerruns a policy table in place of the roles. - Enterprise SSO: attach a customer's identity provider to their organization, so their people join it on first sign-in.
- Email: verification, which is what makes an invitation acceptable.
- Databases: the composite user and joining plugin tables.
- Migrations and maintenance:
auth sweep, which clears expired invitations. - The plugin's README is the reference for its routes, tables and errors.