feat(openapi,cli): workspace switch + member management

[lin-snow]

Summary

Adds workspace switching and member management to the bearer-authenticated /openapi/v1 surface, plus the matching difyctl commands. These endpoints are role-gated against the caller's membership in the target workspace, so they are safe to expose to programmatic (CLI / API) clients.

New /openapi/v1 endpoints

Method	Route	Access	Purpose
POST	/workspaces/{id}/switch	any member	Switch the bearer's active workspace
GET	/workspaces/{id}/members	any member	List members (paginated: page / limit)
POST	/workspaces/{id}/members	owner / admin	Invite a member
PUT	/workspaces/{id}/members/{member_id}/role	owner / admin	Change a member's role
DELETE	/workspaces/{id}/members/{member_id}	owner / admin	Remove a member

A new @require_workspace_role(*roles) decorator centralizes the gate. It returns 404 for non-members (parity with GET /workspaces/{id} — no cross-tenant ID leak) and 403 for members whose role is not allowed. Member invites additionally pass through edition-aware quota gates.

Request flow

sequenceDiagram
    participant CLI as difyctl
    participant API as /openapi/v1
    participant Gate as require_workspace_role
    CLI->>API: Bearer dfoa_… + workspace_id
    API->>API: validate_bearer → set_auth_ctx (ContextVar)
    API->>Gate: accept_subjects(ACCOUNT)
    Gate->>Gate: try_get_auth_ctx() → account_id
    Gate->>Gate: lookup TenantAccountJoin(workspace_id, account_id)
    alt not a member
        Gate-->>CLI: 404
    else role not allowed
        Gate-->>CLI: 403
    else
        Gate->>API: invoke handler → 200
    end

Loading

New difyctl commands

Command	Notes
difyctl use workspace	Set the active workspace for the current host
difyctl get member	List members; --page / --limit pagination
difyctl create member	Invite a member
difyctl set member	Update a member's role
difyctl delete member	Remove a member

create / set / delete member accept -o json|yaml|name|text; auth devices list also gained --page / --limit.

Included fix

require_workspace_role and the member handlers now read the caller identity from the openapi auth ContextVar (try_get_auth_ctx() / get_auth_ctx()), the slot validate_bearer actually publishes — not flask.g.auth_ctx, which production never writes. The earlier flask.g read made every role-gated request raise RuntimeError → 500 while unit tests stayed green (they seeded g directly). A regression test now seeds only g, leaves the ContextVar empty, and asserts the gate still rejects — pinning the identity source.

Test plan

• Backend: api/tests/unit_tests/controllers/openapi/auth/test_role_gate.py (gate: 404 / 403 / pass, query scoping, wiring-bug RuntimeErrors) and test_workspaces_members.py (endpoint behaviors).
• CLI: unit tests per command against a stub server (*.test.ts).
• Manual: exercised all endpoints against a live EE server via curl and the real difyctl binary — switch / list / invite / role-change / remove all return expected results.

Checklist

• This change requires a documentation update, included: Dify Document
• I understand that this PR may be closed in case there was no previous discussion or issues. (This doesn't apply to typos!)
• I've added a test for each change that was introduced, and I tried as much as possible to make a single atomic change.
• I've updated the documentation accordingly.
• I ran make lint && make type-check (backend) and cd web && pnpm exec vp staged (frontend) to appease the lint gods

[github-actions]

Pyrefly Diff

base → PR

--- /tmp/pyrefly_base.txt	2026-05-27 02:53:07.462020242 +0000
+++ /tmp/pyrefly_pr.txt	2026-05-27 02:52:55.195987879 +0000
@@ -555,7 +555,7 @@
 ERROR No matching overload found for function `redis.client.Redis.__init__` called with arguments: (host=int | str | Unknown, port=int | str | Unknown, password=int | str | Unknown | None, db=int, ssl=bool, ssl_ca_certs=str | None, ssl_cert_reqs=Any | None, ssl_certfile=Any | None, ssl_keyfile=Any | None, socket_timeout=Literal[5], socket_connect_timeout=Literal[5], health_check_interval=Literal[30]) [no-matching-overload]
   --> schedule/queue_monitor_task.py:14:21
 ERROR Object of class `Tenant` has no attribute `role` [missing-attribute]
-    --> services/account_service.py:1355:13
+    --> services/account_service.py:1383:13
 ERROR `+` is not supported between `str` and `dict[Unknown, Unknown]` [unsupported-operation]
    --> services/app_service.py:519:53
 ERROR No matching overload found for function `flask.helpers.stream_with_context` called with arguments: (Generator[bytes]) [no-matching-overload]
@@ -2297,6 +2297,26 @@
   --> tests/unit_tests/controllers/openapi/test_workspaces.py:49:12
 ERROR `in` is not supported between `Literal['GET']` and `None` [not-iterable]
   --> tests/unit_tests/controllers/openapi/test_workspaces.py:50:12
+ERROR Object of class `FunctionType` has no attribute `view_class` [missing-attribute]
+   --> tests/unit_tests/controllers/openapi/test_workspaces_members.py:164:12
+ERROR `in` is not supported between `Literal['POST']` and `None` [not-iterable]
+   --> tests/unit_tests/controllers/openapi/test_workspaces_members.py:165:12
+ERROR Object of class `FunctionType` has no attribute `view_class` [missing-attribute]
+   --> tests/unit_tests/controllers/openapi/test_workspaces_members.py:170:12
+ERROR `in` is not supported between `Literal['GET']` and `None` [not-iterable]
+   --> tests/unit_tests/controllers/openapi/test_workspaces_members.py:171:12
+ERROR `in` is not supported between `Literal['POST']` and `None` [not-iterable]
+   --> tests/unit_tests/controllers/openapi/test_workspaces_members.py:172:12
+ERROR Object of class `FunctionType` has no attribute `view_class` [missing-attribute]
+   --> tests/unit_tests/controllers/openapi/test_workspaces_members.py:177:12
+ERROR `in` is not supported between `Literal['DELETE']` and `None` [not-iterable]
+   --> tests/unit_tests/controllers/openapi/test_workspaces_members.py:178:12
+ERROR Object of class `FunctionType` has no attribute `view_class` [missing-attribute]
+   --> tests/unit_tests/controllers/openapi/test_workspaces_members.py:183:12
+ERROR `in` is not supported between `Literal['PUT']` and `None` [not-iterable]
+   --> tests/unit_tests/controllers/openapi/test_workspaces_members.py:184:12
+ERROR Object of class `NoneType` has no attribute `json`
+ERROR Object of class `NoneType` has no attribute `json`
 ERROR Cannot index into `Iterable[bytes]` [bad-index]
    --> tests/unit_tests/controllers/service_api/app/test_audio.py:190:16
 ERROR Cannot index into `Response` [bad-index]

[github-actions]

Pyrefly Type Coverage

Metric	Base	PR	Delta
Type coverage	45.81%	45.73%	-0.07%
Strict coverage	45.33%	45.26%	-0.07%
Typed symbols	24,416	24,434	+18
Untyped symbols	29,191	29,300	+109
Modules	2733	2736	+3

[lin-snow]

😡😡😡 what the fking merge queue doing....