PR 7 — Partner Onboarding (Space Admin UI + Zitadel Org Grants)

This PR lights up the partner-side experience built on PR6's schema. It delivers:

The space-admin UI used by partner-org admins (Accenture admin) to add their own users to groups exposed by the customer (Google).
Zitadel Org Grants integration so a partner-org user logging in can acquire an acting_for token claim scoped to the customer.
An organization-switcher in Console for users who hold memberships across multiple customers' spaces.

Depends on PR 6. Schema and resolver are already in place; this PR is mostly UI + auth-token plumbing + onboarding workflow.

1. Goal

Space admin UI: list users in their partner org, drag/drop into exposed groups, view their org's effective access.
Zitadel Org Grant lifecycle: when customer admin appoints Accenture-org as a space, automate the Zitadel grant API call so Accenture users can authenticate to Console.
acting_for token claim: user's home org is Accenture but their authorization context is Google (the customer). Token carries both; middleware uses acting_for for resource scoping.
Org switcher in Console top bar for users who admin multiple spaces.
Onboarding wizard: customer admin creates space + invites partner admin
- bootstraps first group exposure in one flow.

Non-goals

Partner-org admin self-creating new partner orgs.
Cross-customer aggregates for partner users ("show me all my work across Google + Microsoft").
Customer admin remotely managing partner-org user roster (that's the partner's HR system).
Multi-IdP per partner (each partner = one Zitadel org).

1. Accenture user opens console.exto.com, clicks Login.
2. Zitadel IdP-discovery routes them to Accenture's IdP (their corporate SSO).
3. Zitadel issues token with:
     sub: accenture_user_id
     urn:zitadel:iam:user:resourceowner:id: accenture_org_id   (home org)
     urn:zitadel:iam:org:project:roles: { ... }                (per-grant)
4. Console reads token. Middleware looks up:
     - Is this user a member of group_memberships in any customer? Yes.
     - Which customers? → derived list.
5. If 1 customer → set acting_for automatically.
6. If >1 customer → org-switcher prompt: "You have access via Accenture
     to: Google, Microsoft. Choose:"
7. Once acting_for chosen → set as request claim, resolver runs against it.

The acting_for is session-level, like Focus Mode (PR2) but for partner users it's not optional — they always act for one customer at a time.

Token claim shape

Add to RequestClaims:

type RequestClaims struct {
    // existing
    Sub          string
    HomeOrgID    string

    // PR7
    ActingForCustomerID *uuid.UUID  // nil for direct customer users / internal
}

Resolution in internal/auth/middleware.go:

if isPartnerUser(claims) {       // home_org != customer_org and != admin_org
    actingFor := readActingForCookie(c.Request, claims.Sub)
    if actingFor == nil {
        // Redirect to /switch-customer
        c.AbortWithStatusJSON(409, gin.H{"error": "select customer"})
        return
    }
    claims.ActingForCustomerID = &actingFor.CustomerID
}

Effective grants resolver from PR6 then runs scoped to ActingForCustomerID.

3. Zitadel Org Grants

Zitadel's Org Grants feature: an org can grant another org a project role. We use it to model the Customer→Partner relationship.

When a customer admin creates a space and appoints Accenture as the partner org (PR6 endpoint POST /spaces/:sid/admins), Console:

Calls Zitadel API:

POST /management/v1/orgs/{customer_org_id}/grants
Body: {
  granted_org_id: accenture_org_id,
  project_id:     console_project_id,
  role_keys:      ["space_admin"]    // Console-defined Zitadel role
}

Stores Zitadel grant ID in spaces.zitadel_grant_id for cleanup.
On space archival or partner-org change, Console deletes the Zitadel grant.

Without this grant, Accenture users cannot authenticate to Console for Google's customer context — Zitadel rejects them at the IdP layer. With the grant, Accenture users see "Console" as an authorized app in their Zitadel app catalog.

Why use Zitadel for this and not just Console DB

Zitadel handles the cross-org consent, IdP federation, and revocation at the identity layer. Building the same in Console = duplicating SSO plumbing. Zitadel feature exists; use it.

Schema addition

sql

ALTER TABLE spaces
  ADD COLUMN zitadel_grant_id TEXT,
  ADD COLUMN partner_org_zitadel_id TEXT;

Filled when partner-org-binding is set; null until then. Allows creating a space with no partner yet (for staging) and binding later.

4. Space-admin UI

Drag-and-drop / picker

The primary action is membership management. UI:

Two-column layout: left = my org users (filterable), right = groups.
Drag user → group OR multi-select user(s) + click "Add to group".
Remove via row-level menu.

Boring on purpose. No role/permission visibility. Space admin sees what they need to do their job (memberships) and nothing else.

Partner users see a stripped sidebar:

Item	Visibility
Switch Customer	If user has multiple acting_for options
My Workspace	Routes to `/customers/:acting_for/...`
My Organization	Visible only to space admins
Account	Always (own profile)

The "My Workspace" routes are filtered by the partner user's resolved permissions — same code path as direct customer users, the resolver just sourced from groups instead of portal_role.

5. Onboarding wizard (customer-admin side)

/customers/:id/spaces/new is a 4-step wizard:

Name the space. "Accenture", "AWS Pro Services", etc.
Pick or invite partner org.
- If Accenture already exists in Zitadel and has done business with us before → pick from list.
- Otherwise → invite by domain: enter accenture.com, email an admin contact, Console creates a Zitadel org placeholder and triggers verification. Until partner accepts, space is pending.
Expose initial groups. Multi-select existing groups; or "Create new group" inline shortcut.
Invite first space admin. Email + name. On accept, they're added to space_admins and provisioned via Zitadel grant.

After step 4, customer admin sees a summary card on the space detail page with "Pending" state until partner accepts.

Pending-state lifecycle

State	Trigger	Visible to
`pending`	Space created, partner invite sent, not yet accepted	Customer admin only
`active`	Partner admin accepts invite + Zitadel grant succeeds	Customer admin + space admin
`archived`	Customer admin archives the space	Customer admin (read-only)
`revoked`	Customer admin revokes Zitadel grant; partner cuts off	Customer admin + audit only

Add state enum column to spaces.

6. Endpoints

Space admin (partner)

Method	Path	Purpose
GET	`/api/v1/me/spaces`	My admined spaces (already in PR6)
GET	`/api/v1/spaces/:sid/my-org-users`	Users in partner org (from Zitadel)
POST	`/api/v1/spaces/:sid/groups/:gid/members`	Add member (must be from partner org)
DELETE	`/api/v1/spaces/:sid/groups/:gid/members/:uid`	Remove member

Boundary checks in POST /spaces/:sid/groups/:gid/members:

Caller is in space_admins for this space → 403 if not
Group is in space_group_grants for this space → 403 if not
Target user's home_org matches spaces.partner_org_zitadel_id → 403 otherwise (cannot add a Google user to Accenture-Space)

These three checks together = the entire delegation security boundary. Test them individually; integration-test the conjunction.

Method	Path	Purpose
GET	`/api/v1/me/acting-for`	Current acting_for + list of options
POST	`/api/v1/me/acting-for`	Set acting_for to `{customerId}` (writes cookie)
DELETE	`/api/v1/me/acting-for`	Clear (re-prompts switcher)

Cookie shape mirrors PR2 focus cookie:

console_acting_for=v1.<base64(customerID|expiresAt|hmac)>
HttpOnly; Secure; SameSite=Strict; Path=/api
Max-Age: 86400  (24h, longer than focus mode since it's a primary working context)

Key difference vs PR2: focus mode is optional narrowing for any internal user; acting-for is mandatory selection for partner users.

7. Audit log

Action	Subject	Target
`partner.space.zitadel_grant_created`	system + customer admin	(space, partner_org_id)
`partner.space.zitadel_grant_revoked`	system + customer admin	(space, partner_org_id)
`partner.space.invite_sent`	customer admin	(space, email)
`partner.space.invite_accepted`	partner admin (first login)	space
`partner.acting_for.entered`	partner user	customer
`partner.acting_for.exited`	partner user	customer
`partner.acting_for.switched`	partner user	new customer
`partner.group.member_added` (already in PR6)	space admin	(group, user)

Acting-for transitions are higher-noise than focus-mode transitions (every partner user does it on every login). Sample at 1/N or batch by session if log volume becomes a concern.

8. Tests

Layer	Test
Zitadel	Mocked grant create/delete on space lifecycle
Middleware	Partner user without `acting_for` cookie → 409 "select customer"
Middleware	Partner user's `acting_for` → resolver runs scoped to that customer
Endpoints	Space admin can add member from partner org → 200
Endpoints	Space admin tries to add user from a different org → 403
Endpoints	Space admin tries to add to a group not exposed to their space → 403
Endpoints	Random partner user (not space admin) tries to add member → 403
Endpoints	`POST /me/acting-for` with customer the user has no membership for → 403
E2E manual	Full onboarding: customer admin invites Accenture → Accenture accepts → Accenture admin adds Bob → Bob logs in, picks Google, can read tenant
E2E manual	Partner user with multiple `acting_for` options sees switcher; choosing one isolates queries
E2E manual	Customer admin archives space → partner users next request gets 403; subsequent login gets "no spaces"

9. Implementation order

Step	Layer	Description
1	DB	Migration `009_spaces_state_and_zitadel.sql` (state enum, zitadel ids)
2	Backend	Zitadel client wrapper for org-grants (create / delete / lookup)
3	Backend	`internal/auth/middleware.go` — partner-user detection + acting_for cookie
4	Backend	`/me/acting-for` endpoints
5	Backend	Space-admin write endpoints + boundary checks
6	Backend	`/spaces/:sid/my-org-users` proxying Zitadel for partner-org user list
7	Backend	Space lifecycle integration: state transitions + Zitadel grant calls
8	Backend	Audit log entries
9	Tests	Mocked Zitadel + boundary-check matrix
10	Frontend	Acting-for switcher + cookie wiring
11	Frontend	Partner-user sidebar layout
12	Frontend	Space-admin UI (members, groups read-only, my-org)
13	Frontend	Customer-admin onboarding wizard
14	Docs	Update `docs/roles-and-permissions.md` with partner section
15	Ops	Runbook: how to invite a partner, how to revoke, how to debug a stuck Zitadel grant

10. Risk register

Risk	Mitigation
Zitadel grant API call fails after space row created → orphan space	Two-phase commit: create space in `pending`, only mark `active` after grant succeeds; cleanup job for stale pending
Partner user's home org changes (rebrand, reorg) — old grants point to dead org	Zitadel emits org events; consume webhook + mark spaces `revoked` automatically
Partner admin adds the same user to many groups → permission union surprises customer	Customer-admin UI shows effective permissions per partner user (computed); audit-friendly
`acting_for` cookie HMAC drift if user's sub changes (impossible in Zitadel? confirm)	HMAC bound to sub; if mismatch, force re-pick
Partner user with no `acting_for` chosen yet hits a deep-linked URL	409 redirects to `/switch-customer`; preserves return-to
Zitadel rate limits on org-grant creation during bulk customer onboarding	Queue + retry; surface "pending" state honestly to customer admin
Customer admin revokes a space while partner user mid-session	Resolver re-runs each request → next request 403/redirected to switcher; cookie expiry caps blast radius
Partner user simultaneously a customer-portal user of another customer	Token has `home_org`; resolver picks correct path. Both shouldn't grant unintended cross-access — covered by drift test

PR 7 — Partner Onboarding (Space Admin UI + Zitadel Org Grants)

1. Goal

Non-goals

Token claim shape

3. Zitadel Org Grants

Why use Zitadel for this and not just Console DB

Schema addition

4. Space-admin UI

Pages

Drag-and-drop / picker

Sidebar (partner user)

5. Onboarding wizard (customer-admin side)

Pending-state lifecycle

6. Endpoints

Space admin (partner)

7. Audit log

8. Tests

9. Implementation order

10. Risk register

PR 7 — Partner Onboarding (Space Admin UI + Zitadel Org Grants) ​

1. Goal ​

Non-goals ​

2. Auth flow — partner user login ​

Token claim shape ​

3. Zitadel Org Grants ​

Why use Zitadel for this and not just Console DB ​

Schema addition ​

4. Space-admin UI ​

Pages ​

Drag-and-drop / picker ​

Sidebar (partner user) ​

5. Onboarding wizard (customer-admin side) ​

Pending-state lifecycle ​

6. Endpoints ​

Space admin (partner) ​

Acting-for cookie ​

7. Audit log ​

8. Tests ​

9. Implementation order ​

10. Risk register ​

PR 7 — Partner Onboarding (Space Admin UI + Zitadel Org Grants)

1. Goal

Non-goals

2. Auth flow — partner user login

Token claim shape

3. Zitadel Org Grants

Why use Zitadel for this and not just Console DB

Schema addition

4. Space-admin UI

Pages

Drag-and-drop / picker

Sidebar (partner user)

5. Onboarding wizard (customer-admin side)

Pending-state lifecycle

6. Endpoints

Space admin (partner)

Acting-for cookie

7. Audit log

8. Tests

9. Implementation order

10. Risk register