Management

APIs related to system management tasks.

📄️ List mail servers

Returns configured mail servers. Requires system-settings.view.

Creates a mail server. Requires system-settings.fullaccess. If Enabled is true, SMTP is tested first; a failed test still creates the server with Enabled false. Enabling one server disables the others. Service users are rejected (GE-1014).

📄️ Get a mail server

Returns one mail server and its SMTP HealthStatus. Requires system-settings.view. Password is not returned. Service users are rejected (GE-1014).

📄️ Update a mail server

Updates a mail server. Requires system-settings.manage. Omitted fields are copied from the stored item; omitted Password is copied from SSM. Enabling one server disables the others. Service users are rejected (GE-1014).

📄️ Delete a mail server

Deletes a mail server from DynamoDB and its SSM credentials. Requires system-settings.fullaccess. Unknown ids are not rejected with 400; SSM delete or audit then fails as 500. Service users are rejected (GE-1014).

📄️ List roles

Returns a paginated list of roles. A Super Admin sees every role on the platform; any other caller sees only the roles they are attached to.

📄️ Create a new access role

Creates a new access role. The caller automatically becomes a role manager, and every role manager is added to UsersAttached.

📄️ Get role details

Returns the full detail of a single role, including RoleConsolidatedPermissions: the effective permission set after expanding the transitive dependencies of RolePermissions. That field is always computed and cannot be requested or suppressed.

📄️ Update a role

Updates a role's metadata, permissions or attached users. Only a role manager (or a Super Admin) may call this.

📄️ Delete a role

Triggers deletion of an access role. Only a role manager (or a Super Admin) may call this.

📄️ Check health of AWS resources

Returns DWH, OpenSearch, S3, SSM, DynamoDB, Squid proxy, and SMTP status. Requires system-settings.view. Individual probes that fail are returned as undetermined or not available, not as HTTP 500.

📄️ Submit user feedback

Stores the caller's feedback. Message is required. IssueName, Path, and StackTrace default to n/a when omitted.

📄️ Get cost and usage for a month

Returns Cost Explorer usage for the month in the path (YYYY-MM). Requires system-settings.view. Future months return GE-1001. latest=yes reads Cost Explorer live and omits LastUpdatedTime. Any other latest value (default no) reads the latest DynamoDB snapshot for that month, or Cost Explorer if none exists.

📄️ Publish CICD or SDK usage metrics

Publishes a usage payload to the usage SNS topic for CICD or SDK traffic. Requires header X-Source of cicd or sdk; other values are treated as invalid. usageMetricsFor must be cicd or sdk (exact case). There is no extra permission check. role_id is recorded in audit logs. This handler catches validation errors inside send_custom_app_usage_sns and returns HTTP 500 with GE-1008, not 400.

📄️ Creates a SAML group to role/tag mapping based on user input

Creates role or tag mappings for a SAML group. Requires IdP to be enabled. SamlGroupId must be in IdpName#GroupName format. Use Roles when mappingType is role, or Tags when mappingType is tag.

📄️ Lists all the group mappings available

Returns paginated SAML group mappings for the given mappingType, grouped by SAML group.

📄️ Updates a SAML group to role mapping or tag mapping based on user input

Diff-based update of role or tag mappings for a SAML group. Requires IdP to be enabled. Path samlGroupId must be in IdpName#GroupName format. Use Roles when mappingType is role, or Tags when mappingType is tag.

📄️ Returns a SAML group to role/tag mapping based on user input

Returns all role or tag mappings for a SAML group. Path samlGroupId must be in IdpName#GroupName format. Response SamlGroupId is the group name only.

📄️ Deletes a SAML group to role/tag mapping based on user input

Deletes all role or tag mappings for a SAML group. Path samlGroupId must be in IdpName#GroupName format. No request body.

📄️ List user agreements

Returns metadata for every user agreement in the system. Requires system-settings.view. The response is not paginated; the full list is returned in one call. Optional projectionExpression limits which fields appear on each item (comma-separated names, not trimmed).

📄️ Create a user agreement

Creates a new user agreement. Requires system-settings.fullaccess. The body must include AgreementName, Description, and TermsOfUse and no other keys (IPV-1008). AgreementName must be 3-120 characters, start with a letter, use only letters, digits, and underscores, and be unique case-insensitively (IPV-1004, IPV-1018).TermsOfUse is the markdown file as a base64 string; it is stored and a new Version (unix epoch seconds) is returned. Repeating the same body creates a new version unless the name already exists.

📄️ Get a user agreement by version

Returns the user agreement for the Version path value plus an S3PresignedUrl for the markdown file (expires in 3600 seconds). Requires system-settings.view. Does not create a default agreement when the version is missing (IPV-1002).

📄️ Get the latest user agreement

Returns the user agreement with the highest Version (unix epoch string, sorted descending) plus an S3PresignedUrl for the markdown file (expires in 3600 seconds). The handler does not check system-settings.view. A missing role_id does not return AUTH-1001; it is stored as N/A on the audit log. If no agreements exist, Default_User_Agreement is created (CreatedBy System) and returned. Not paginated.

📄️ Get account Lambda concurrency limit

Returns the AWS account ConcurrentExecutions limit for this region. Requires system-settings.view. If AWS does not return that limit, 1000 is used.

📄️ Get deployment identity

Returns Version, Environment, ProjectName, ProjectShortname, AWSRegion, and AWSAccountId from Lambda environment variables. Any valid authenticated user may call this; there is no extra permission. role_id is recorded in audit logs. Invalid user returns GE-1060.

📄️ Get system information and configuration

Returns deployment identity (Version, Environment, ProjectName, ProjectShortname, AWSRegion, AWSAccountId) when no query parameters are sent. Use config for one stored setting, or config=all for identity plus every setting. Matching is case-insensitive. Any valid authenticated user may call this; there is no extra permission. RAG and web-search settings are returned only when AI services are enabled; otherwise those config values return GE-1034.

📄️ Update a named system configuration

Updates one stored setting selected by the required config query parameter (IPV-1052 if omitted). Requires system-settings.manage. web-search-configuration also requires ai.manage; missing that permission returns AUTH-1030 as HTTP 400. Request body fields depend on config. Matching is case-insensitive. ai-services-configuration is not a supported update target (GE-1034) even though the handler still requires ai.manage before rejecting it.

📄️ Get Squid proxy instance patch compliance status

Returns EC2 state and SSM patch compliance for the InService Squid proxy instance. Requires system-settings.view. Only available when managed Squid proxy is enabled.

📄️ List Squid proxy instance patches

Returns SSM patches for the InService Squid proxy instance. Requires system-settings.view. Only available when managed Squid proxy is enabled.

📄️ Trigger Squid proxy patch operation

Queues a Scan or ScanAndInstall on the InService Squid proxy instance and returns immediately. Poll GET /proxy/instance/patchstatus for progress. Requires system-settings.manage. Only available when managed Squid proxy is enabled. Not idempotent; a second call while Status is Pending or InProgress returns GE-1034.