AWS Organizations ExecModule

Overview

The AWS Organizations ExecModule turns a multi-account AWS estate into bounded, reviewable workflow input. Cloud-platform, security, FinOps, and compliance teams can inventory member accounts, trace the hierarchy that owns them, inspect enabled policy families, correlate policies with their targets, and discover delegated administrators and services without copying raw credentials or policy documents into a workflow.

This connector is intentionally read-only. It cannot create or close accounts, move accounts, create or attach policies, change organizational units, register delegated administrators, enable trusted access, or change organization settings. Those actions can carry broad blast radius and require separate change controls.

Every operation uses the AWS Organizations global endpoint through a verified IntegrationAccount. Lists are bounded, continuation tokens remain opaque, transient reads use controlled retries, and operation-specific validation rejects unexpected fields before provider access. Account email addresses are not returned. describe_policy returns policy metadata plus a SHA-256 digest and character count of the policy content—not the raw policy document.

AWS Organizations exposes the organization structure and direct policy attachments. A direct attachment alone does not calculate every policy that effectively applies after inheritance, and organization membership does not prove that each account is correctly configured. Use the connector to build evidence and routing context, then keep evaluation, approval, remediation, and verification as explicit downstream steps.

Usage

Use an AWS Organizations management-account identity, or a delegated context that AWS authorizes for the selected read operation.
Grant only the Organizations read actions used by the workflow.
Store the access-key pair in a ValkyrAI IntegrationAccount, verify it, and keep it in READY status.
Add AwsOrganizationsModule and bind the account through ExecModuleConfig.authConfig.integrationAccount.
Start with describe_organization and list_roots to establish organization and policy-family context.
Traverse roots and organizational units with explicit parentId and childId values returned by prior calls.
Use limit for a deliberate total bound. Enable returnAll only when the downstream workflow is prepared for every page up to that bound.
Preserve account IDs, OU IDs, policy IDs, target IDs, and policy-content hashes when deduplicating or reconciling work.

AWS Organizations is a global service. The connector does not accept a region or custom endpoint, which prevents workflows from redirecting credentialed requests to arbitrary hosts.

Inputs

Input	Type	Required	Default	Description
`operation`	string	Yes	—	One supported AWS Organizations read operation.
`nextToken`	string	No	—	Opaque continuation token returned by AWS.
`limit`	integer	No	`100`	Total list bound from 1 to 1,000 items.
`returnAll`	boolean	No	`false`	Follow provider pages until `limit` or exhaustion.
`accountId`	string	Operation-specific	—	Exact 12-digit AWS account ID.
`parentId`	string	Operation-specific	—	Exact root ID such as `r-abcd` or OU ID such as `ou-abcd-12345678`.
`childId`	string	`list_parents`	—	Exact account or OU ID.
`policyId`	string	Policy detail/targets	—	Exact Organizations policy ID such as `p-12345678`.
`policyType`	string	Policy list operations	—	Supported governance policy family.
`targetId`	string	`list_policies_for_target`	—	Exact account, root, or OU target ID.
`servicePrincipal`	string	No	—	Optional service-principal filter for delegated administrators.

Supported policy types are SERVICE_CONTROL_POLICY, RESOURCE_CONTROL_POLICY, TAG_POLICY, BACKUP_POLICY, AISERVICES_OPT_OUT_POLICY, CHATBOT_POLICY, and DECLARATIVE_POLICY_EC2.

Unknown or operation-inappropriate fields are rejected. Raw access keys, secret keys, session tokens, authorization headers, credential maps, regions, and endpoint overrides are never accepted as workflow input.

Outputs

Every operation returns a stable envelope:

Output	Description
`status`	`success` or `error`.
`operation`	Normalized operation name.
`attempts`	Provider calls, including pages and safe read retries.
`resultType`	Result family such as `accounts`, `organizational_units`, `policies`, or `delegated_services`.
`items` / `count`	Bounded normalized list results and returned count.
`pages` / `hasMore` / `nextToken`	Pagination evidence for list operations.
`data`	One normalized organization, account, or policy detail.
`requestId`	AWS request identifier when safely available.
`error`	Stable code, redacted message, HTTP status, and retryability.

Account output includes ID, ARN, name, status, join method, and join timestamp. It deliberately excludes the account email address. Organization output includes the organization ID and ARN, feature set, management-account ID, and available policy families. Root output includes root identity and per-root policy-family status.

Policy summaries include ID, ARN, name, bounded description, type, and whether AWS manages the policy. Exact policy detail adds contentLength and contentSha256. The policy body never enters workflow output. This lets a workflow detect or correlate a reviewed policy revision without distributing its statements more broadly.

IntegrationAccount Requirements

Use an AWS IntegrationAccount with:

status: READY
verified: true
access key ID in the account API-key field
secret access key in the protected password field

The connector never reads credentials from workflow input. It creates an AWS Organizations SDK client only after account verification and disables SDK-level retries so ValkyrAI can report exact attempt counts.

A deployment may need only the actions its reviewed workflows call:

organizations:DescribeOrganization
organizations:ListAccounts
organizations:DescribeAccount
organizations:ListRoots
organizations:ListOrganizationalUnitsForParent
organizations:ListAccountsForParent
organizations:ListParents
organizations:ListPolicies
organizations:DescribePolicy
organizations:ListPoliciesForTarget
organizations:ListTargetsForPolicy
organizations:ListDelegatedAdministrators
organizations:ListDelegatedServicesForAccount

Do not grant account lifecycle, hierarchy mutation, policy mutation, policy attachment, trusted-access, delegated-administrator mutation, or wildcard Organizations access merely to satisfy this connector. AWS may further limit some reads to the management account or a supported delegated context.

Configuration

ExecModuleConfig supplies the IntegrationAccount and optional retry policy. The connector has no region field because AWS Organizations is global. All operations are reads and retry transient throttling, server, and network failures up to the configured maximum, bounded from one to five attempts. The default is three.

Provider pages request at most 20 items, matching the Organizations API's conservative page size. ValkyrAI can follow up to 100 pages but never returns more than the caller's limit or the hard total bound of 1,000.

The AWS SDK retry policy is disabled inside the connector. This keeps ValkyrAI's attempts field authoritative and avoids hidden replay behavior.

Operations

Organization and account inventory

describe_organization — return organization identity, feature set, management-account ID, and available policy types.
list_accounts — list bounded member-account metadata across the organization.
describe_account — retrieve one exact member account.
list_roots — list organization roots and enabled policy types.

These operations provide inventory evidence at request time. A returned account can still have stale ownership metadata or incomplete security onboarding, so route results through accountable review rather than treating membership as proof of readiness.

Hierarchy traversal

list_organizational_units_for_parent — list direct child OUs below one root or OU.
list_accounts_for_parent — list direct child accounts below one root or OU.
list_parents — find the direct parent of one account or OU.

Traversal is deliberately one relationship at a time. Workflows can build a reviewed hierarchy breadth-first while preserving explicit bounds and source IDs. The connector does not infer business ownership from OU names.

Governance policy evidence

list_policies — list one supported policy family.
describe_policy — return policy metadata plus a content length and SHA-256 digest.
list_policies_for_target — list policies of one family attached directly to an account, root, or OU.
list_targets_for_policy — list accounts, roots, and OUs directly targeted by one policy.

Direct attachments are not an effective-policy calculator. Service control policies and other governance policy families can inherit through the organization hierarchy, and policy semantics differ by family. Use account, parent, and attachment data together, then evaluate the effective outcome with the appropriate AWS service and change-control process.

Delegated administration

list_delegated_administrators — list delegated administrator accounts, optionally filtered by service principal.
list_delegated_services_for_account — list services delegated to one exact account.

These operations help route GuardDuty, Security Hub, Macie, Detective, Inspector, Firewall Manager, Config, and similar organization-wide workflows to the right administration account. They do not prove that service enrollment, regional coverage, or delegated configuration is healthy.

Errors and Failure Modes

Code	Meaning	Retry guidance
`VALIDATION_ERROR`	A required ID, policy type, service principal, token, or bound is invalid.	Correct input; no provider call was made.
`INTEGRATION_ACCOUNT_ERROR`	The account is missing, unverified, not `READY`, or incomplete.	Repair and verify the account.
`UNSUPPORTED_OPERATION`	The operation is outside this read-only release.	Select one documented operation.
`AWS_ORGANIZATIONS_HTTP_400`	AWS rejected an identifier, filter, or organization state.	Correct the request and inspect the request ID.
`AWS_ORGANIZATIONS_HTTP_403`	IAM or Organizations context denied the read.	Use the management account or add only the missing read action.
`AWS_ORGANIZATIONS_HTTP_404`	The account, OU, root, policy, or target was not found.	Reconcile the exact ID and organization.
`AWS_ORGANIZATIONS_HTTP_429` / `500` / `502` / `503` / `504`	Throttling or transient provider pressure.	Bounded read retries are automatic.
`NETWORK_ERROR`	ValkyrAI could not reach AWS Organizations.	Verify connectivity and retry the read.
`EXECUTION_ERROR`	An unexpected local failure was safely contained.	Inspect server logs; provider details and credentials remain redacted.

Provider exception text is never returned to workflow output. AWS request IDs are preserved when safely available for CloudTrail and support correlation.

Example

Build a bounded account inventory for one organizational unit:

{
  "operation": "list_accounts_for_parent",
  "parentId": "ou-abcd-12345678",
  "returnAll": true,
  "limit": 100
}

Expected result shape:

{
  "status": "success",
  "operation": "list_accounts_for_parent",
  "attempts": 1,
  "resultType": "accounts",
  "items": [
    {
      "accountId": "111122223333",
      "accountArn": "arn:aws:organizations::111122223333:account/o-example/111122223333",
      "name": "Production",
      "status": "ACTIVE",
      "joinedMethod": "CREATED",
      "joinedTimestamp": "2026-01-15T18:30:00Z"
    }
  ],
  "count": 1,
  "pages": 1,
  "hasMore": false,
  "requestId": "example-request-id"
}

Use each account ID to check delegated services, discover direct policy attachments, and route service-specific posture checks. Keep business ownership, exception decisions, and remediation approval in their authoritative systems rather than inferring them from account or OU names.

Notes

Pagination: Provider tokens are opaque and can expire. returnAll follows no more than 100 pages and never returns more than 1,000 items.
Rate limits: Every operation is read-only and retries transient failures with bounded backoff and at most five configured attempts.
API limits: Each provider page requests at most 20 results. Identifiers, service principals, and continuation tokens have strict local bounds.
Idempotency: Every supported operation is repeatable and has no provider-side mutation.
Global endpoint: The connector always uses the AWS Organizations global endpoint and rejects region or endpoint overrides.
Policy privacy: Raw policy content is not returned. describe_policy exposes only metadata, content length, and SHA-256 digest.
Account privacy: Account email addresses are excluded from normalized output.
Inheritance: Direct policy attachments are evidence, not a complete effective-policy calculation.
Credential boundary: Live AWS behavior remains unverified until an authorized least-privilege non-production organization account is supplied.
Deferred capabilities: Account creation/closure, invitations, account moves, OU lifecycle, policy lifecycle, policy attachment, tag mutation, policy-type enablement, trusted access, delegated-administrator mutation, and handshake operations are intentionally deferred.
Destructive behavior: None. This release cannot change organization membership, hierarchy, policies, or delegated administration.
Runtime boundary: Merged source and published documentation do not update the deployed Workflow Studio catalog until a ValkyrAI backend release exposes AwsOrganizationsModule through /v1/modules/metadata.

Overview​

Usage​

Inputs​

Outputs​

IntegrationAccount Requirements​

Configuration​

Operations​

Organization and account inventory​

Hierarchy traversal​

Governance policy evidence​

Delegated administration​

Errors and Failure Modes​

Example​

Notes​

Related resources​