CloudRoleManager — API Sequence Diagrams

sequenceDiagram actor User participant App as Tenant App participant CRM as CloudRoleManager User->>App: Fill registration form\n(org name, email, password) App->>CRM: POST /api/v1/auth/register alt Success CRM-->>App: 201 {org_id, user_id, message} App-->>User: "Registration successful — please log in" else Org name or email already taken CRM-->>App: 409 {error: "Organisation name or email already exists"} App-->>User: Show error message else Missing / invalid fields CRM-->>App: 400 {error: "..."} App-->>User: Show validation error end

sequenceDiagram actor User participant App as Tenant App participant CRM as CloudRoleManager User->>App: Enter username + password App->>CRM: POST /api/v1/auth/login alt Valid credentials CRM-->>App: 200 {access_token (15 min), refresh_token (30 days), user} App->>App: Store tokens App-->>User: Redirect to dashboard else Wrong credentials or inactive account CRM-->>App: 401 {error: "Invalid credentials"} App-->>User: Show error end Note over App,CRM: For project apps (machine-to-machine), use the project login endpoint App->>CRM: POST /api/v1/auth/project/login\n{username, password, jwt_seed, tenant_id} Note over App,CRM: jwt_seed + tenant_id identify the application\nand its JWT signing secret alt Valid credentials and valid application credentials CRM-->>App: 200 {access_token, refresh_token, user} App->>App: Store tokens else Invalid jwt_seed / tenant_id CRM-->>App: 401 {error: "Invalid application credentials"} end Note over App,CRM: Access token expires after 15 minutes App->>CRM: POST /api/v1/auth/refresh\n{refresh_token} alt Refresh token valid CRM-->>App: 200 {access_token} App->>App: Replace stored access token else Refresh token expired or revoked CRM-->>App: 401 App-->>User: Redirect to login end User->>App: Click Logout App->>CRM: POST /api/v1/auth/logout\n{refresh_token} CRM-->>App: 200 {ok: true} App->>App: Clear stored tokens App-->>User: Redirect to login

sequenceDiagram actor User participant App as Tenant App participant CRM as CloudRoleManager User->>App: Navigate to a protected section App->>CRM: GET /api/v1/admin/... (Authorization: Bearer token) alt Token valid CRM-->>App: 200 data App-->>User: Render content else Token expired CRM-->>App: 401 Unauthorized App->>CRM: POST /api/v1/auth/refresh CRM-->>App: 200 new access_token App->>CRM: Retry original request CRM-->>App: 200 data App-->>User: Render content else Refresh token also expired CRM-->>App: 401 Unauthorized App-->>User: Redirect to login end

sequenceDiagram actor User participant App as Tenant App participant CRM as CloudRoleManager User->>App: Request a resource requiring "content:read" alt Option A — Shared JWT secret (no network call) App->>App: Decode token locally\nCheck projects[pid].permissions includes "content:read" alt Has permission App-->>User: 200 Resource else Missing permission App-->>User: 403 Forbidden end else Option B — Introspect endpoint App->>CRM: POST /api/v1/auth/introspect\n{token} alt Token active CRM-->>App: 200 {active: true, projects, permissions, ...} App->>App: Check permissions in response App-->>User: 200 Resource else Token invalid or expired CRM-->>App: 401 {active: false} App-->>User: 401 Unauthorized end end

sequenceDiagram actor Admin participant App as Tenant App participant CRM as CloudRoleManager Admin->>App: Create role "moderator" (level 25) under "editor" App->>CRM: POST /api/v1/admin/projects/:pid/roles\n{name, level, parent_role_id} alt Parent level constraint violated CRM-->>App: 400 {error: "Parent level must be strictly less than child level"} App-->>Admin: Show error else Cycle in hierarchy detected CRM-->>App: 400 {error: "Cycle detected..."} App-->>Admin: Show error else Success CRM-->>App: 201 {id, name, level} App-->>Admin: Role created end Admin->>App: Assign permission "content:edit" to "moderator" App->>CRM: POST /api/v1/admin/projects/:pid/roles/:id/permissions/:perm_id CRM-->>App: 200 {ok: true} App-->>Admin: Permission assigned Note over Admin,CRM: Next login for any user with "moderator" role\nwill include "content:edit" + all inherited permissions in their JWT

sequenceDiagram actor Admin participant App as Tenant App participant CRM as CloudRoleManager Admin->>App: Invite new user (email, password, role) App->>CRM: POST /api/v1/admin/users\n{email, username, password, role_ids} alt Email or username already exists CRM-->>App: 409 {error: "Email or username already exists"} App-->>Admin: Show error else Success CRM-->>App: 201 {id, email, username} App-->>Admin: User created end Admin->>App: Assign additional role to user App->>CRM: POST /api/v1/admin/users/:id/roles/:role_id CRM-->>App: 200 {ok: true} Admin->>App: Deactivate user App->>CRM: DELETE /api/v1/admin/users/:id CRM-->>App: 200 {ok: true} App-->>Admin: User deactivated\n(existing tokens expire naturally after 15 min)

sequenceDiagram actor Admin participant App as Tenant App participant CRM as CloudRoleManager Admin->>App: Open audit log (page 1) App->>CRM: GET /api/v1/admin/audit?page=1&per_page=50 CRM-->>App: 200 {data: [...events], total, page, per_page} App-->>Admin: Show paginated event table Admin->>App: Go to next page App->>CRM: GET /api/v1/admin/audit?page=2&per_page=50 CRM-->>App: 200 {data: [...events], total, page, per_page} App-->>Admin: Show next page Note over CRM: Audit log is immutable —\nno update or delete is possible

sequenceDiagram actor Admin participant UI as CRM UI participant CRM as CloudRoleManager participant ConsumerApp as Consumer App Admin->>UI: Create application UI->>CRM: POST /api/v1/admin/applications CRM-->>UI: 201 {id, name, ...} Admin->>UI: Link project to application UI->>CRM: POST /api/v1/admin/applications/:id/project\n{project_id} CRM-->>UI: 201 {jwt_seed, tenant_id, jwt_secret, ...} Note over UI,Admin: jwt_seed is shown ONCE here — copy it now\njwt_secret can be viewed again at any time Admin->>ConsumerApp: Configure app with jwt_seed + tenant_id + jwt_secret ConsumerApp->>CRM: POST /api/v1/auth/project/login\n{username, password, jwt_seed, tenant_id} CRM-->>ConsumerApp: 200 {access_token, refresh_token, user} Note over Admin,CRM: On data breach — rotate the jwt_secret Admin->>UI: Rotate secret UI->>CRM: POST /api/v1/admin/applications/:id/project/rotate-secret CRM-->>UI: 200 {jwt_secret: ""} Note over CRM,ConsumerApp: All existing tokens immediately invalid\nUsers must re-login Note over Admin,CRM: On config compromise — rotate the jwt_seed Admin->>UI: Rotate seed UI->>CRM: POST /api/v1/admin/applications/:id/project/rotate-seed CRM-->>UI: 200 {jwt_seed: ""} Note over CRM: Logs seed_rotated to audit changelog Note over UI,ConsumerApp: Consumer app config must be updated\nwith new jwt_seed before project logins work again