Skip to content

Support Session Management Architecture

Status: Draft for Review System: Angular + Spring Boot 4.0.5 (Java 25) + Auth0 Date: October 2026 Driver: Sky Ledge support engineers must be able to act inside a customer organization to diagnose and fix problems, without sharing customer credentials and without ever obtaining the organization’s API keys Author: Nimash


Table of Contents

  1. Problem & Design
  2. System Actors
  3. Session Lifecycle
  4. API
  5. Support Session Cookie & Request Origin Check
  6. Who May Open and Use a Session
  7. Offboarding
  8. Permission Scope
  9. Audit Trail
  10. Security Controls & Attack Scenarios
  11. Known Gaps & Production Readiness

1. Problem & Design

Every user belongs to exactly one organization, and the invitation signup flow guarantees that only an organization can add members to itself. Support engineers belong to the Sky Ledge support organization, so by construction they can’t see or touch a customer’s data. Support work still needs that access occasionally, and it must be granted in a way that is narrower, shorter-lived and more visible than membership.

Core principle: a support session is a time-boxed, reasoned, audited grant for one engineer to act in one target organization. The engineer never gets a new identity. They stay logged in with their own BFF session (the SESSION cookie, relayed to their own Auth0 JWT), and a second cookie, SUPPORT_SESSION, names the support session they are currently working in. While that cookie is present and the session is valid, the API server resolves the request as the target organization’s owner.

This builds on the cookie-based BFF login documented in cookie-based-authentication-implemantation/architecture.md; JWT validation and SESSION → bearer relay are not re-derived here.

Property Description
Grant, not membership The session itself never makes the engineer a member of the target organization. A READ_WRITE session can still make changes that outlive it, such as an invite or a registered device (accepted risk, §8).
Time-boxed Every session has an expiresAt between 1 and 120 minutes (2 hours) after creation. Expiry is checked on every request, and an expired session can’t be extended: an officer who needs longer creates a new session, with a new reason.
Reasoned A non-blank reason is mandatory on creation and stored with the session.
Scoped READ_ONLY or READ_WRITE. /api-key is blocked in every session regardless of scope.
Revocable The officer who opened a session, or the support organization owner, can revoke it. Revocation, logout, exit and deactivating the engineer all end access. Revocation is effective on the very next request because the session is re-read from the database every time.
Audited Every write made in a session, successful or not, is sent to the support-audit-log-queue SQS FIFO queue with method, path, status, IP, duration and body. Refused reads and refused session attempts are sent too, without a body. Other reads are not audited.
Cookie-carried The session id travels in an HttpOnly cookie set by the server, so page scripts can’t read or forge it.

2. System Actors

Actor Role Trust
Angular SPA Creates a session, enters it (server sets the cookie), shows support mode via GET /support/sessions/current, exits or revokes. Never sees the session id in a header. Partial
Browser Carries SESSION (BFF login) and SUPPORT_SESSION (current support session) on every same-site request, and sends the Sec-Fetch-* and Origin headers used by the request origin check. Untrusted
Spring Boot — apiServerChain (@Order(3)) Filter order is load-bearing: ApiKeyFilter → SessionTokenRelayFilter → BearerTokenAuthenticationFilter → SupportSessionFilter → SupportPermissionScopeFilter. Support handling runs only after the engineer’s own JWT is validated. Fully trusted
SupportSessionAwareAuthProvider (@Primary AuthProvider) If the request carries an active session, resolves userIdFromPrincipal to the target organization’s owner and organizationIdFromPrincipal to the target organization. Otherwise delegates to AuthProviderAuth0Adapter. Fully trusted
Spring Boot — bffLoginChain /bff/logout deletes SUPPORT_SESSION together with SESSION and JSESSIONID. Fully trusted
PostgreSQL support_session One row per session: engineer id and email, target organization, reason, scope, created_at, expires_at, revoked_at, revoked_by, last_activity_at. Never deleted. Trusted
SQS FIFO support-audit-log-queue One message per mutating request made in a session, whatever its outcome (§9). The application never reads it back. Trusted

3. Session Lifecycle

There are two independent states: whether the session is still valid, and whether the engineer’s browser is currently in support mode (holds the cookie).

Session: [created] ──▶ ACTIVE ──(expires_at passes)──────────────────▶ EXPIRED
│
└──(DELETE /support/sessions/{id}, or engineer deactivated)──▶ REVOKED
Browser: normal ──(POST /{id}/enter: Set-Cookie SUPPORT_SESSION)──▶ support mode
support mode ──(POST /exit | revoke of current | /bff/logout | any dead-session refusal)──▶ normal
Transition Set by
Created SupportSessionCreator.create(): checks the engineer is active and has fewer than support.max-concurrent-sessions (env SUPPORT_MAX_CONCURRENT_SESSIONS, default 5 when unset) active sessions, then saves with expiresAt = now + durationMinutes. At the limit it is refused with 409. Creating does not enter the session.
Entered EnterSupportSessionController: loads the session only if it is active and owned by the caller, then writes the cookie with max-age equal to the session’s remaining lifetime.
Activity SupportSessionFilter → SupportSessionLookup.recordActivityOn() sets last_activity_at with a single UPDATE of that column only, and only if it is empty or more than a minute old. It never writes the rest of the row, so it can’t undo a revocation that happens while the request is running, and a burst of requests writes at most once a minute.
Exited ExitSupportSessionController: clears the cookie. The session stays active and can be entered again until it expires.
Revoked SupportSessionRevoker sets revoked_at/revoked_by. Only the officer who owns the session or the support organization owner may revoke it; anyone else gets 403. Revoking a session that has already expired or been revoked is refused with 409. If the revoked session is the one in the caller’s cookie, the cookie is cleared in the same response.
Expired Implicit: isActive() is !revoked && expiresAt > now. No job; checked on read. At most 2 hours after creation. Expired sessions can’t be renewed or extended; the officer creates a new one.

The cookie never outlives the session by design (max-age = remaining lifetime), and if it does survive (clock drift, revocation from another tab), the first request with a dead session clears it.


4. API

All endpoints live under /support/sessions. SupportSessionFilter lets these requests through without activating the session even when the cookie is present, so they always see the real engineer, never the target organization’s owner.

Callers

Caller Who that is
Support officer Any user whose organization is the support organization (support.skyledge-organization-id), including its owner.
Support organization owner The owner of the support organization. An officer with extra rights over other officers’ sessions.
Customer user Any logged-in user outside the support organization, including a target organization’s owner and its members.
Unauthenticated No valid SESSION cookie or bearer token. apiServerChain requires authentication on every /support/sessions/** endpoint, so these always get 401.
API key A request authenticated with an organization’s API key. SupportSessionFilter refuses every /support/sessions/** request with 403 before it reaches a controller, whichever organization the key belongs to (§6).

Access is enforced by @PreAuthorize on SupportSessionCreator, SupportSessionRetriever and SupportSessionRevoker, decided by SupportSessionPermissionChecker. exit and the no-cookie path of current have no permission check beyond being logged in.

Endpoints

Method & path Purpose Who can call Who is refused Notes
POST /support/sessions Create a session Support officer, for themselves only Customer user: 403. Also 403 if the target organization doesn’t exist, is the caller’s own organization, or the caller is deactivated. 409 at the concurrent-session limit. Body: targetOrganizationId, reason, permissionScope (READ_ONLY / READ_WRITE), durationMinutes (1–120, i.e. at most 2 hours); invalid body 400. Returns 201.
POST /support/sessions/{id}/enter Enter support mode Support officer, only into their own active session Customer user: 403. Officer whose session id is unknown, expired, revoked or belongs to another officer: 404. The support organization owner can’t enter another officer’s session either (404). Sets SUPPORT_SESSION.
POST /support/sessions/exit Leave support mode Any authenticated user, support officer or customer user Only unauthenticated (401) and API key (403). Clears the cookie. Returns 204. Does not revoke.
GET /support/sessions/current What the SPA should show Support officer. Any authenticated user may call it, but only an officer ever gets a session back. Only unauthenticated (401) and API key (403). 200 with the session if the cookie names an active session owned by the caller. 410 Gone with the ended session (its expiresAt and revokedAt say which) if that session has expired or been revoked; the cookie is cleared. 204 if there is no cookie. Also 204, with the cookie cleared, if the cookie is malformed, names no session, names another officer’s session, or the caller is a customer user, so nothing about other sessions is revealed.
GET /support/sessions List the caller’s own active sessions Support officer (always their own; there is no parameter to ask for someone else’s) Customer user: 403.
GET /support/sessions/active List every officer’s active sessions Support organization owner only Other support officers and customer users: 403. Optional targetOrganizationId narrows it to the sessions currently open into one organization, i.e. who is inside a customer organization right now. A malformed id returns 400.
GET /support/sessions/{id} Get one session The officer who owns it, or the support organization owner (any session) Another officer, or a customer user: 403. An officer asking for an unknown id also gets 403; the support organization owner gets 404.
DELETE /support/sessions/{id} Revoke The officer who owns it, or the support organization owner (any officer’s session) Another officer, or a customer user: 403 (also for an unknown id, except the support organization owner gets 404). 409 if the session has already expired or been revoked. Clears the cookie if it names this session.

Endpoint × caller summary

Endpoint Support officer Support organization owner Any other organization user/owner (incl. target organization owner) Unauthenticated API key
POST /support/sessions ✅ for self ✅ for self ❌ 403 ❌ 401 ❌ 403
POST /support/sessions/{id}/enter ✅ own active only ✅ own active only ❌ 403 ❌ 401 ❌ 403
POST /support/sessions/exit ✅ ✅ ✅ ❌ 401 ❌ 403
GET /support/sessions/current ✅ ✅ ✅ always 204 ❌ 401 ❌ 403
GET /support/sessions ✅ own ✅ own ❌ 403 ❌ 401 ❌ 403
GET /support/sessions/active ❌ 403 ✅ all ❌ 403 ❌ 401 ❌ 403
GET /support/sessions/{id} ✅ own only ✅ any ❌ 403 ❌ 401 ❌ 403
DELETE /support/sessions/{id} ✅ own only ✅ any ❌ 403 ❌ 401 ❌ 403

The target organization’s owner has no say over sessions opened into their organization: they can’t list, view, revoke or be notified of them (consent and notification are planned for v2, §11).


Cookie (SupportSessionCookie):

Attribute Value Why
Name SUPPORT_SESSION
Value The session UUID It is only a pointer. It grants nothing on its own; the server re-checks ownership and validity every request.
HttpOnly true Page scripts (including an XSS payload) can’t read or set it.
Secure server.servlet.session.cookie.secure (default true) Same setting as the BFF SESSION cookie.
SameSite Lax Not sent on cross-site sub-requests (fetch/XHR/forms with POST).
Path /
Max-Age Remaining session lifetime; 0 to clear

Request origin check. CSRF protection is disabled on apiServerChain, and SameSite=Lax still sends the cookie on top-level cross-site GET navigations. So SupportSessionFilter only accepts a support session request when it can tell the request came from the app itself:

  1. Sec-Fetch-Mode: navigate → refused. A support session is never activated by a page load or a link click, only by the SPA’s own API calls.
  2. Sec-Fetch-Site: same-origin → accepted.
  3. Otherwise, Origin must be one of incontrol.api-client.cors-allowed-origins → accepted; anything else → refused with 403.

A request without the cookie skips all of this and is handled normally, and so do /support/sessions/** and /bff/password-change even with the cookie, because they always act as the engineer (§6). The one exception is an API-key request to /support/sessions/**, which is refused with or without the cookie (§6).


6. Who May Open and Use a Session

Creating (SupportSessionPermissionChecker, via @PreAuthorize on SupportSessionCreator):

  • The caller’s organization is support.skyledge-organization-id, set through the SUPPORT_SKYLEDGE_ORGANIZATION_ID environment variable (application.yaml defaults it to to_be_provided). If the value is not a UUID, every support session permission check fails with an IllegalStateException (500) whose message names the missing variable, so the misconfiguration shows up in the logs instead of as a silent 403.
  • The command’s supportUserId is the caller. An engineer can’t open a session for someone else.
  • The target organization exists.
  • The target organization is not the caller’s own organization.
  • The caller’s user record is active (checked in SupportSessionCreator).
  • The caller has fewer than support.max-concurrent-sessions active sessions (default 5 when the SUPPORT_MAX_CONCURRENT_SESSIONS environment variable is not set).

Viewing and revoking:

Caller List own sessions List every officer’s sessions (/active) View or revoke a session
Officer (support organization member) Yes No Only their own
Support organization owner Yes Yes Any officer’s
Anyone else No No No

“Support organization owner” is the owner of the organization configured as support.skyledge-organization-id.

Using a session. An engineer in support mode acts as the customer organization’s owner, but only when every one of these holds for the request:

  1. It comes from a person, not an integration. Requests made with an organization’s API key never act inside a support session. An API key is a machine credential of one organization; letting it ride a session would let a key from the support organization act in any customer organization.
  2. It isn’t managing sessions or changing the engineer’s own password. Creating, entering, exiting, listing and revoking sessions, and /bff/password-change, always act as the engineer themselves, never as the customer’s owner. The password change is a page load, which rule 4 would otherwise refuse, so an engineer in support mode can still change their own password.
  3. The engineer is logged in. Without a valid login the support session is simply ignored; the request is treated like any other unauthenticated request.
  4. It comes from the Sky Ledge app. Not from a link, a page load or another website (§5).
  5. The session exists and belongs to this engineer. An engineer can never use a colleague’s session, even with its id.
  6. The session is still active. It hasn’t expired or been revoked.

If check 1, 4, 5 or 6 fails, the request is refused and the attempt is recorded in the audit trail (§9). When the session is missing, belongs to someone else or has ended (5 and 6), the engineer is also dropped back to normal mode. A request refused for coming from outside the app (4) leaves support mode untouched, so a malicious link can’t end it. Once every check passes, the request acts as the customer organization’s owner, limited by the session’s scope (§8).


7. Offboarding

Deactivating a user blocks them in Auth0, but the access token they already hold stays valid until it expires. Without offboarding, a deactivated engineer could keep using open support sessions, or open new ones into any customer organization, during that window.

UserUpdater (deactivate)
└─ publishes UserDeactivatedEvent(userId, deactivatedBy)
└─ UserDeactivatedEventHandler.revokeActiveSupportSessions() (synchronous @EventListener)
└─ revoke every active session of userId with revoked_by = deactivating admin

The listener is synchronous: it runs on the deactivating request’s thread, so every active session is already revoked when the deactivation call returns, with no window in which an open session still works. Creating a session additionally requires the engineer to be active, so a new session can’t be opened either. Because SupportSessionFilter re-reads the session on every request, the revocation takes effect on the next request and clears the cookie.


8. Permission Scope

SupportPermissionScopeFilter runs only when a session is attached to the request. Paths are URL-decoded before matching.

The filter applies three rules in order:

  1. /api-key(/…) is blocked in every session, for every method and regardless of scope (403 This endpoint is not available during a support session.).
  2. READ_ONLY sessions reject any method other than GET, HEAD and OPTIONS, except POST …/search, which is a read (403 Support session is read-only…).
  3. READ_WRITE sessions may call every other endpoint.

Why /api-key is the only blocked path

While a session is active, SupportSessionAwareAuthProvider resolves the caller as the target organization’s owner, so every request runs with the owner’s full authority inside an organization the engineer does not belong to. Sky Ledge accepts that a READ_WRITE session can do anything the owner can, with one exception:

Path Methods What the endpoint does Why it stays blocked
/api-key(/…) All, including reads GET /api-key returns the organization’s live API key values and creates any missing key types on the fly (ApiKeyRetriever). Credential exfiltration. One read would hand the engineer a long-lived organization credential that works from anywhere, with no session, scope, audit or expiry. API-key requests can never carry a support session (§6), so anything done with the key bypasses this design entirely. Because the “read” also mints keys, it is a write in disguise, so blocking writes only would not be enough.

The path is matched after URL decoding, so encoded variants such as /%61pi-key can’t slip past. A blocked write is sent to the audit queue with status 403, and a blocked GET /api-key is sent as a lightweight refused-request event without a body (§9).

Accepted risks

Every other endpoint is open in a READ_WRITE session. These are the risks that come with it, accepted on the basis that support engineers are trusted Sky Ledge staff and that every write is audited (§9):

Path What a support engineer can now do Accepted risk
/users/invite(/…) Invite people into the customer’s organization through the invitation signup flow. Self-invite escalation. The engineer could invite their own email, or one they control. Redeeming it creates a real member account that is not time-boxed, not scope-limited and not removed by revocation, expiry or deactivating the engineer, so temporary support access can become standing access to the customer’s organization.
/controlrooms/{id}/invite(/…) Assign collaborators to a control room; invitees without an account are invited into the organization (UserInviteRequestedEvent). The same self-invite escalation, reached through control-room collaboration.
/users(/…) writes POST /users creates a user directly. PUT /users/{id} sets a user’s active flag, which also blocks or unblocks them in Auth0. Planting or reviving an account, such as a former employee or an account the engineer controls. Locking customers out by deactivating their users, including the owner.
/me(/…) writes /me is the organization owner during a session: profile (PUT /me), push-notification devices (PUT /me/devices), notification preferences, mailing list. Changes in the owner’s name on their personal profile. Persistence through notifications: a device the engineer registers on the owner’s account keeps receiving the owner’s push notifications after the session ends. Preference changes can silently stop the owner receiving alerts.
/organization(/…) writes PUT /organization changes the organization’s name and time zone. POST /organization creates a new organization. Organization-wide side effects that are hard to notice afterwards (customer-facing name, schedules and date boundaries), and creating a tenant on the owner’s behalf.
/billing(/…) View plan, invoices and payment methods; POST /billing/payment-methods authorizes a payment method. Financial data exposure and financial commitments made in the customer’s name.

Because of these, a session that has ended no longer guarantees that the engineer has nothing left in the organization: an invite, a created or revived user, or a registered device can outlive it. The audit trail (§9) is what makes such changes visible after the fact.

Why READ_ONLY treats POST …/search as a read

Several list endpoints take their filters in a POST body because the filter is too complex for a query string. They change nothing, so a read-only engineer needs them to see the same lists as the customer. Every other POST, PUT, PATCH and DELETE is refused in a READ_ONLY session.


9. Audit Trail

Audit events are not stored in the database. Each audited request becomes one text message on the SQS FIFO queue support-audit-log-queue (support-audit-log-queue.fifo on AWS, since FIFO queue names must end in .fifo). Storing and querying the trail is the queue consumer’s job, not the API server’s. The earlier support_audit_log table is dropped (V202610261200__drop_support_audit_log.sql); any rows it held are deleted.

What is audited. Every request that can change data: every method other than GET, HEAD and OPTIONS. That covers POST, PUT, PATCH and DELETE, and includes POST …/search, which READ_ONLY sessions treat as a read (§8). Reads are audited only when they are refused. Every attempt that SupportSessionFilter refuses is audited as well, even though no valid session is attached.

SupportSessionFilter lets reads through without capturing their body, and wraps every accepted write in a ContentCachingRequestWrapper and times it. Because the engineer acts with the organization owner’s authority, the body is what makes a support change reconstructable: the path says what was called, the body says what was changed.

Outcome Where it goes
Write, any response (2xx, 4xx, 5xx, including 403s from SupportPermissionScopeFilter) A SUPPORT_REQUEST message with the request body. Writes refused by the scope filter, such as a READ_ONLY write or a write to /api-key, are on the queue alongside successful changes. If an exception escapes the request handling, the event records status 500 rather than the status the response had at that moment.
Read refused by SupportPermissionScopeFilter (a GET /api-key) A lightweight REFUSED_SUPPORT_REQUEST message: the same fields without a request body.
Any other read (GET, HEAD, OPTIONS) Nothing.
Refused by SupportSessionFilter (no valid session to attach the event to) A REFUSED_SUPPORT_SESSION message, plus a structured WARN log line Session Management Audit: refused reason=…. The reason is one of API_KEY_NOT_ALLOWED, UNTRUSTED_REQUEST_ORIGIN, MALFORMED_SESSION_ID, SESSION_NOT_FOUND, SESSION_EXPIRED_OR_REVOKED.
Message fails to send ERROR log line in the API server logs, and the request carries on; it has already been answered.
Revoked by deactivation INFO log line with the count, user and revoking admin.

Message. One message per request. Its body is a single JSON text document holding the whole event, request body included:

{
"eventId": "6f1c…",
"timestamp": "2026-10-26T03:14:07.512Z",
"sessionId": "2b7e…",
"supportUserId": "a91d…",
"supportUserEmail": "engineer@skyledge.com",
"targetOrganizationId": "c40f…",
"requestMethod": "PUT",
"requestUri": "/controlrooms/8d2a…",
"responseStatus": 200,
"clientIp": "203.0.113.7",
"durationMs": 42,
"requestBody": "{\"name\":\"Pump 4\"}",
"requestBodyTruncated": false,
"eventType": "SUPPORT_REQUEST"
}

A REFUSED_SUPPORT_REQUEST has the same fields, with requestBody null. A REFUSED_SUPPORT_SESSION describes an attempt that never reached a session:

{
"eventId": "91aa…",
"timestamp": "2026-10-26T03:15:42.004Z",
"reason": "SESSION_EXPIRED_OR_REVOKED",
"supportUserId": "a91d…",
"requestedSessionId": "2b7e…",
"requestMethod": "PUT",
"requestUri": "/controlrooms/8d2a…",
"responseStatus": 401,
"clientIp": "203.0.113.7",
"eventType": "REFUSED_SUPPORT_SESSION"
}

supportUserId is null when the request carries no verified engineer, and requestedSessionId is the session id exactly as sent, so it may not be a valid id.

SQS attribute Value Why
MessageGroupId sessionId; for REFUSED_SUPPORT_SESSION, the engineer id (or unauthenticated) Events of one session are delivered in the order they happened, while different sessions don’t hold each other up.
MessageDeduplicationId A new random id per send, generated by Spring Cloud AWS The queue uses explicit deduplication (ContentBasedDeduplication=false, as for every FIFO queue MessageQueueCreator creates). Two identical requests within the 5-minute deduplication window are two separate events and must both arrive, so content-based deduplication would be wrong. Consumers deduplicate on eventId.
token, correlationId Added by MessageSenderSQSAdapter to every message On audit messages token is masked to **** plus the last 4 characters of the engineer’s access token, so the queue never holds a usable token. Other queues still get the full token, which their listeners need to act as the caller.

The queue is the SUPPORT_AUDIT_LOG_QUEUE FIFO entry in the MessageQueue enum, so MessageQueueCreator creates it, with its dead-letter queue, at startup like rule-execution-fifo-queue. Sending goes through the existing MessageSender (MessageSenderSQSAdapter). The payload is built by SupportAuditMessageComposer from a SupportAuditEvent.

Sending is asynchronous. The filter builds the SupportAuditEvent from the request and response on the request thread, then hands the composing and sending to the application TaskExecutor, so the response doesn’t wait for SQS. The caller’s security context and logging context (correlation id) are carried over to the sending thread.

Request body recording:

Content type Recorded as
text/*, application/json, application/xml, application/x-www-form-urlencoded, any +json / +xml type, or no content type The body as text in the request’s charset (UTF-8 by default). Null when empty.
Anything else (multipart/form-data, application/octet-stream, images, …) A placeholder, e.g. [multipart/form-data body, 2048 bytes not recorded], so file uploads don’t fill the queue with decoded binary. The size is omitted when the request has no Content-Length.

Bodies are sent in full unless they don’t fit in one message. SQS accepts at most 1 MiB (1,048,576 bytes) per message, attributes included. The JSON payload is capped at 983,040 bytes (SupportAuditMessage.MAX_PAYLOAD_BYTES), leaving 64 KiB for the message attributes.

  • If the whole event fits, the body is sent exactly as received and requestBodyTruncated is false.
  • Otherwise SupportAuditMessageComposer keeps the longest prefix of the body that still fits, measured in UTF-8 bytes after JSON escaping and never splitting a character, and sets requestBodyTruncated to true.
  • The request wrapper caches at most the payload limit plus one byte, so an oversized body is never held in memory in full.

All log lines share the Session Management Audit: prefix so they can be queried together.


10. Security Controls & Attack Scenarios

Blocked endpoints and accepted risks

/api-key is the only endpoint blocked in a session, for reads as well as writes, so a session can never hand the engineer a long-lived organization credential that works outside this design (§8).

Every other owner capability is available in a READ_WRITE session, and its risks are accepted (§8):

Accepted risk Endpoints
Self-invite escalation: a permanent member account for the engineer in the customer’s organization /users/invite, /controlrooms/{id}/invite, POST /users
Reviving a removed user, or locking customers out PUT /users/{id}
Persisting through the owner’s identity (push devices, notification preferences, profile) /me writes
Organization-wide side effects (name, time zone, new tenant) /organization writes
Financial data and commitments /billing

The mitigations are that sessions are reasoned, time-boxed and revocable, engineers are trusted Sky Ledge staff, and every write in a session is on the audit queue (§9).


11. Known Gaps & Production Readiness

Open

Gap Impact Plan
Nothing consumes the audit queue yet. MessageQueueCreator gives queues a 4-day retention, so until the queue is consumed, audit events are lost after 4 days. Route the queue through Amazon Data Firehose into a secure S3 bucket, set up purely in AWS: sc-12042.

Accepted

Behaviour Why it is accepted
Actions are attributed to the organization owner in the customer’s own data (created-by, updated-by, activity feeds). The support audit trail records which officer made each change.
READ_WRITE sessions have the owner’s full authority except /api-key. An engineer can invite themselves, create or revive users, register devices on the owner’s account, change organization settings and see or change billing. Accepted behaviour; every write is on the audit queue (§8).
Only /api-key is blocked. /api-key is the only endpoint that returns credentials.
A failed send doesn’t fail the request. The API server logs an ERROR and carries on; support work is not blocked by an SQS problem.
Audit events waiting to be sent can be lost when an instance stops or crashes, because they are sent after the response from a thread pool. Accepted.
Request bodies are sent as received, sensitive values included. The audit logs are stored in a secure S3 bucket.
Bodies over the message limit are truncated (about 960 KB); requestBodyTruncated flags it. Accepted.

Planned for v2

Feature Note
Customer consent and notification Customers aren’t told when support enters their organization. Notifying the owner, and optionally requiring approval, is planned for v2 of the feature.