Epic 12 — Admin Tenancy & Access Control
Covers organisation settings, role assignment (BU / AP / OP / AU), user invitations, and SSO role mapping for enterprise deployments. All stories in this epic require the OP (Operator/Admin) role.
Personas: OP (exclusive)
Shared modules:
CorrelationChip
EnvProvenance
Story 12.1 — View Organisation Settings
- As an
- OP
- I want
- to view and edit the organisation-level settings for my AMTP tenant
- So that
- I can configure defaults that apply to all users and projects
Scenario: Organisation settings page loads
Giventhe Operator navigates to
/admin/settings
WhenGET /admin/settings resolves
Thenthe settings page renders: organisation name, tenant ID, default pipeline depth, allowed frameworks, quota limits, and SSO configuration state
Scenario: Edit organisation settings
Whenthe Operator modifies a setting and saves
Then
PATCH /admin/settings is issued with the changed fields; updated values are reflected immediately; an Epic 15 audit-log entry is written for the change
| Endpoint / DB | Purpose |
|---|---|
GET /admin/settings | Organisation-wide settings |
PATCH /admin/settings | Update settings; audited |
Story 12.2 — Assign and Change User Roles
- As an
- OP
- I want
- to assign or change a user's role within the tenant
- So that
- each user has the correct level of access for their responsibilities
Scenario: Role change applied immediately
Giventhe Operator is on the user management page (
/admin/users) and selects a user
Whenthe Operator selects a new role (BU / AP / OP / AU) from the role picker and confirms
ThenPATCH /admin/users/{user_id} is issued with { "role": "<new_role>" }; the role badge in the user list updates immediately; the affected user's session token is invalidated server-side on the next request
Scenario: Operator cannot downgrade their own role
Giventhe currently authenticated Operator is viewing their own user row
Thenthe role picker is disabled for that row with tooltip You cannot change your own role;
PATCH /admin/users/{own_user_id} is never issued
| Endpoint / DB | Purpose |
|---|---|
GET /admin/users | User list with current roles |
PATCH /admin/users/{user_id} | Update role; audited |
Story 12.3 — Invite a New User
- As an
- OP
- I want
- to invite a new user to the tenant by email address
- So that
- they can log in and be assigned an appropriate role immediately
Scenario: Invitation email sent successfully
Whenthe Operator fills the invite form (email address, initial role) and clicks Send invitation
Then
POST /admin/invitations is issued; the server sends an invitation email; an Invitation sent confirmation is shown; the pending invitation appears in the user list with a Pending badge and an expiry countdown (typically 72 h)
Scenario: Duplicate invitation blocked
Givenan active invitation already exists for the email address
Whenthe Operator submits the form
Thenthe API returns 409; an inline error reads An active invitation already exists for this email address. Revoke the existing invitation to resend.
Scenario: Revoke pending invitation
Whenthe Operator clicks Revoke on a pending invitation
Then
DELETE /admin/invitations/{invitation_id} is issued; the invitation row is removed from the list; the invitation link in the email is invalidated
| Endpoint / DB | Purpose |
|---|---|
POST /admin/invitations | Send invitation |
DELETE /admin/invitations/{invitation_id} | Revoke invitation |
Story 12.4 — SSO Role Mapping
- As an
- OP
- I want
- to configure a mapping from SSO group claims to AMTP roles
- So that
- users' AMTP roles are automatically assigned based on their enterprise directory groups
Scenario: SSO role mapping applied on login
Giventhe Operator has configured a mapping: SSO group
amtp-operators → AMTP role OP
Whena user who is a member of amtp-operators logs in via SSO
Thenthe user is automatically assigned the OP role; no manual role assignment by the Operator is required
Scenario: SSO group not in mapping — default role applied
Givena user's SSO groups do not match any configured mapping
Thenthe user is assigned the configured default role (typically
BU) and can be promoted manually via Story 12.2
| Endpoint / DB | Purpose |
|---|---|
GET /admin/settings/sso | SSO configuration and role-mapping rules |
PATCH /admin/settings/sso | Update group-to-role mappings and default role |
Story 12.5 — Revoke User Access
- As an
- OP
- I want
- to immediately revoke a user's access to the AMTP tenant
- So that
- off-boarded team members cannot view data or trigger runs
Scenario: User access revoked successfully
Whenthe Operator clicks Revoke access on a user row and confirms the modal
Then
DELETE /admin/users/{user_id} is issued; the user is removed from the user list; all of the user's active session tokens are invalidated server-side immediately; an Epic 15 audit-log entry is written
Scenario: Revocation prevents further API access
Giventhe revoked user's session token is still in their browser
Whenthe revoked user attempts any subsequent API request
Thenthe server returns 401;
SessionRefreshController fails to refresh (cross-link to Epic 1, Story 1.2); the user is redirected to the login surface
| Endpoint / DB | Purpose |
|---|---|
DELETE /admin/users/{user_id} | Revoke user access; invalidates all sessions; audited |