AWS Secrets Manager ExecModule

Overview

AwsSecretsManagerModule brings governed AWS Secrets Manager operations into ValkyrAI workflows. It discovers secret metadata, reads version state, retrieves an explicitly approved value into confidential workflow output, and performs reviewable lifecycle changes. The connector uses ValkyrAI's native map ABI and a verified IntegrationAccount; AWS credentials never belong in workflow input.

The connector implements eleven operations:

• list_secrets, describe_secret, and list_secret_versions expose bounded metadata without secret values.
• get_secret_value retrieves one approved version only after confirmRevealSecret=true.
• create_secret, put_secret_value, and update_secret create or change secret material without echoing it in mutation receipts.
• delete_secret schedules recoverable deletion for 7-30 days, while restore_secret cancels a scheduled deletion.
• rotate_secret configures or starts rotation with a caller UUID token.
• update_version_stage moves a staging label such as AWSCURRENT to a reviewed version.

n8n's reusable AWS credential/region model and AWS Secrets Manager external-secret integration provide the functional workflow reference. ValkyrAI adds a dedicated native module with strict per-operation fields, full-ARN region checks, explicit secret-reveal and mutation confirmations, confidential output classification, read-only retry, recoverable deletion only, and deterministic provider-state reconciliation.

Usage

1. Identify the exact AWS region, secret names or full ARNs, KMS keys, version stages, and rotation function the workflow may access.
2. Create a least-privilege IAM principal restricted to those Secrets Manager actions and resources.
3. Store its access key ID and secret access key in an AWS IntegrationAccount; verify it and keep it in READY status.
4. Add AwsSecretsManagerModule and bind the account through ExecModuleConfig.authConfig.integrationAccount.
5. Use list_secrets, describe_secret, and list_secret_versions before changing state.
6. Set the exact confirmation field for value reads and mutations. Unexpected fields fail before provider access.
7. Reconcile the returned ARN, version ID, staging labels, deletion date, or rotation state after a timeout; never blindly replay a mutation.

Never place an AWS access key, secret key, session token, or credentials object in module input. Those fields are rejected before any network request. Secret names, ARNs, descriptions, tags, KMS references, version IDs, staging labels, rotation configuration, and secret values are confidential and belong only in ACL-scoped workflow state.

Inputs

Name	Type	Required for	Default	Constraints
operation	string	Every execution	None	One of the eleven documented operations.
region	string	Every execution	None	AWS region such as us-west-2; custom endpoints are not accepted.
secretId	string	Existing-secret operations	None	Secret name or complete Secrets Manager ARN whose region matches region; at most 2,048 characters.
secretName	string	create_secret	None	1-512 AWS-safe characters; the reserved aws/ prefix is rejected.
nextToken	string	Optional list field	None	Opaque provider token, at most 4,096 characters.
limit	integer	Optional list field	100	Total result bound from 1 through 10,000.
returnAll	boolean	Optional list field	false	Follow pages until limit, exhaustion, or 100 pages.
includePlannedDeletion	boolean	Optional list_secrets field	false	Include metadata for secrets scheduled for deletion.
includeDeprecated	boolean	Optional version-list field	false	Include versions that have no staging labels.
filters	object	Optional list_secrets field	Empty	Up to 10 AWS filters, each with 1-10 bounded strings.
versionId	string	Optional value read	Provider current version	32-64 safe version-ID characters.
versionStage	string	Optional value/write; required stage move	Provider current stage	Staging label up to 256 characters.
secretString	string	Secret create/version; optional update	None	Exactly one string or binary value; 1-65,536 characters; never echoed in mutation receipts.
secretBinaryBase64	string	Secret create/version; optional update	None	Base64 that decodes to 1-65,536 bytes.
clientRequestToken	string	Create, put, rotate; value-changing update	None	Caller UUID used as the immutable AWS version/idempotency token.
description	string	Optional create/update field	None	Safe text up to 2,048 characters.
kmsKeyId	string	Optional create/update field	AWS managed key	KMS key ID, alias, or ARN up to 2,048 characters.
tags	object	Optional create_secret field	Empty	Up to 50 key/value pairs; aws: keys are rejected.
recoveryWindowDays	integer	Optional delete_secret field	30	7-30 days; immediate force deletion is intentionally unsupported.
rotationLambdaArn	string	Optional rotate_secret field	Existing configuration	Complete same-region Lambda function ARN.
automaticallyAfterDays	integer	Optional rotation rule	Provider default	1-1,000; cannot be combined with scheduleExpression.
rotationDuration	string	Optional rotation rule	Provider default	Bounded hourly duration such as 2h.
scheduleExpression	string	Optional rotation rule	Provider default	Bounded rate(...) or cron(...); cannot be combined with automaticallyAfterDays.
rotateImmediately	boolean	Optional rotate_secret field	true	Whether AWS should start rotation immediately.
moveToVersionId	string	update_version_stage	None	Version that receives versionStage.
removeFromVersionId	string	Optional stage move	Provider inference	Version that loses versionStage.
confirmRevealSecret	boolean	get_secret_value	false	Must be exactly true.
confirmCreateSecret	boolean	create_secret	false	Must be exactly true.
confirmPutSecretValue	boolean	put_secret_value	false	Must be exactly true.
confirmUpdateSecret	boolean	update_secret	false	Must be exactly true.
confirmDeleteSecret	boolean	delete_secret	false	Must be exactly true.
confirmRestoreSecret	boolean	restore_secret	false	Must be exactly true.
confirmRotateSecret	boolean	rotate_secret	false	Must be exactly true.
confirmUpdateVersionStage	boolean	update_version_stage	false	Must be exactly true.

Outputs

Every call returns stable status, operation, and attempts fields.

Name	Type	When present	Description
status	string	Always	success or error.
operation	string	Always	Normalized operation.
attempts	integer	Always	Provider calls including pages and retry-safe reads.
resultType	string	Success	Secret metadata, version, value, or lifecycle receipt family.
items	array	List success	Bounded secret or version metadata.
count	integer	Items are present	Number of returned items.
pages	integer	Paginated success	Provider pages consumed.
hasMore	boolean	Paginated success	Whether AWS returned another token.
nextToken	string	Another page exists	Opaque continuation token.
data	object	Success	Metadata, confidential secret value, or redacted mutation receipt.
requestId	string	AWS supplies one	Bounded request reference for reconciliation.
error	object	Failure	Safe {code, message, httpStatus?, retryable} details.

get_secret_value returns secretString or secretBinaryBase64 because retrieval is the purpose of that operation. The entire module output is classified as secret. Mutation receipts contain only safe identifiers, version/stage state, acceptance markers, deletion timing, and request references; they never repeat submitted secret material.

IntegrationAccount Requirements

Bind one AWS IntegrationAccount through the normalized ExecModule authentication relationship:

Field	Requirement
Provider	Amazon Web Services / Secrets Manager
status	Must be READY.
verified	Must be true.
apiKey SecureField	AWS access key ID.
password SecureField	AWS secret access key.

Grant only the actions enabled for the workflow:

• Discovery: secretsmanager:ListSecrets, secretsmanager:DescribeSecret, and secretsmanager:ListSecretVersionIds.
• Value read: secretsmanager:GetSecretValue; add kms:Decrypt only for the exact approved customer-managed keys.
• Create/version/update: secretsmanager:CreateSecret, secretsmanager:PutSecretValue, and secretsmanager:UpdateSecret; add only the required KMS encrypt/data-key permissions.
• Recoverable lifecycle: secretsmanager:DeleteSecret and secretsmanager:RestoreSecret.
• Rotation/stages: secretsmanager:RotateSecret and secretsmanager:UpdateSecretVersionStage; narrowly scoped lambda:InvokeFunction and iam:PassRole may be required by reviewed rotation designs.
• Tag-based policy conditions can restrict access further, but creation with tags also requires the corresponding tagging authorization.

The connector currently supports a long-lived access-key pair. STS session credentials, role assumption, workload identity, custom endpoints, cross-region replication, batch value retrieval, resource-policy mutation, random-password generation, tag changes after creation, rotation cancellation, and replica removal are deferred.

Configuration

The awsAccount relationship is the only credential configuration. Operation, region, secret, version, pagination, rotation, and safety fields belong in mapped input or module parameters.

{
  "version": "1.0.0",
  "authConfig": {
    "authStrategy": 1,
    "integrationAccount": "integration-account:aws-secrets-manager-production"
  },
  "payloadConfig": {
    "parameters": "{\"operation\":\"get_secret_value\",\"region\":\"us-west-2\"}"
  }
}

The relationship value is illustrative. Persisted workflows bind the generated IntegrationAccount relationship, never plaintext credentials.

Operations

Operation	Provider behavior	Safety and retry behavior
list_secrets	Lists bounded secret metadata with filters and optional planned-deletion visibility.	Read-only; each page retries transient failures.
describe_secret	Reads metadata, tags, rotation rules, dates, and version-to-stage mappings.	Read-only; bounded retry; no secret value.
get_secret_value	Reads one named/ARN version and returns string or base64 binary value.	Requires explicit reveal confirmation; confidential read with bounded retry.
list_secret_versions	Lists bounded version IDs, stages, KMS IDs, and dates.	Read-only; opaque pagination and bounded retry.
create_secret	Creates a secret and its first value using a caller UUID token.	Confirmed mutation; exactly one provider attempt.
put_secret_value	Adds an immutable value version, optionally with a stage label.	Confirmed mutation; caller UUID token; exactly one attempt.
update_secret	Changes description/KMS key and optionally creates a new value version.	Confirmed mutation; value changes require a caller UUID; exactly one attempt.
delete_secret	Schedules deletion after a 7-30 day recovery window.	Destructive but recoverable; confirmed and exactly one attempt.
restore_secret	Cancels scheduled deletion.	Confirmed mutation; exactly one attempt.
rotate_secret	Configures or starts asynchronous rotation with optional Lambda/rules.	Confirmed mutation; caller UUID token; exactly one attempt.
update_version_stage	Moves a staging label to a reviewed version.	Confirmed mutation; exactly one attempt.

Errors and Failure Modes

Code	Typical cause	Retryable	Resolution
VALIDATION_ERROR	Missing/malformed region, secret ID, ARN, value, version, filter, rule, pagination value, or confirmation.	No	Correct the named input; no provider request was sent.
UNSUPPORTED_OPERATION	Unknown operation.	No	Select a documented operation.
INTEGRATION_ACCOUNT_ERROR	Account missing, unverified, not READY, or missing key material.	No	Repair and bind the AWS account.
AWS_SECRETS_MANAGER_HTTP_400	Invalid state, scheduled deletion, version/stage conflict, KMS issue, or reused token with different data.	Reads retry only selected transient codes	Inspect exact provider state and request ID.
AWS_SECRETS_MANAGER_HTTP_403	IAM, KMS, Lambda, tag condition, or resource policy denied.	No	Grant only the missing action/resource/condition.
AWS_SECRETS_MANAGER_HTTP_404	Secret or version no longer exists in the selected region/account.	No	Reconcile the exact complete ARN or name and version.
AWS_SECRETS_MANAGER_HTTP_429 / 500 / 503	Throttle or transient provider pressure.	Reads retry; mutations report ambiguity	Inspect secret/version/stage state before replay.
NETWORK_ERROR	DNS, TLS, timeout, or connectivity failure.	Reads retry; mutations report ambiguity	Treat provider acceptance as unknown until exact state is checked.
EXECUTION_ERROR	Unexpected bounded runtime failure.	No automatic replay	Preserve operation and request evidence for investigation.

Provider exception messages are never copied into workflow output. This prevents access keys, secret values, names, ARNs, tags, descriptions, KMS references, rotation configuration, and provider detail from leaking through errors.

Example

Retrieve one reviewed current secret version:

{
  "operation": "get_secret_value",
  "region": "us-west-2",
  "secretId": "production/payments/api",
  "versionStage": "AWSCURRENT",
  "confirmRevealSecret": true
}

Expected result shape:

{
  "status": "success",
  "operation": "get_secret_value",
  "attempts": 1,
  "resultType": "secret_value",
  "data": {
    "arn": "arn:aws:secretsmanager:us-west-2:123456789012:secret:production/payments/api-example",
    "name": "production/payments/api",
    "versionId": "12345678123442349234123456789012",
    "versionStages": ["AWSCURRENT"],
    "secretString": "[confidential value]"
  },
  "requestId": "aws-request-reference"
}

The result intentionally contains secret material. Bind it directly to the next confidential operation, keep workflow/object ACLs narrow, and avoid logging, email, analytics, or long-lived serialization.

Notes

• Pagination: list_secrets and list_secret_versions return one page unless returnAll=true; the connector follows opaque tokens with unchanged inputs and stops at limit, exhaustion, or 100 pages.
• Rate limits: Secrets Manager quotas and costs vary by account, region, KMS usage, and action. Read calls use at most five configured attempts with bounded backoff. Value and lifecycle mutations never retry automatically.
• API limits: provider list pages are capped at 100; total results at 10,000; filters at 10 with 10 values each; tags at 50; secret string/binary values at 65,536 characters/bytes; descriptions at 2,048 characters; and deletion recovery at 7-30 days. AWS can impose tighter account-, KMS-, Lambda-, or policy-specific limits.
• Idempotency: create, put, value-changing update, and rotate use a caller UUID as the AWS client request/version token. Reusing a token with different secret data fails. A stable token does not make an unknown result safe to replay until the exact secret and version state is reconciled.
• Eventual consistency: list_secrets may lag recent changes. Use describe_secret and list_secret_versions with the exact identifier for reconciliation.
• Rotation: rotation is asynchronous and can leave AWSPENDING on an incomplete version. After acceptance, inspect metadata/version stages and the rotation Lambda before another rotation request.
• Destructive behavior: delete_secret never force-deletes. It schedules deletion with at least seven days of recovery. Deleting a replicated primary can fail until replicas are removed; replica operations are intentionally outside this module.
• Secure values: get_secret_value intentionally places decrypted value material in secret-classified output. secretString and secretBinaryBase64 inputs are passed only to AWS and never copied into mutation receipts or errors. Avoid mapping them into logs, notifications, public content, or non-secret fields.
• KMS: cross-account secret access requires a complete ARN. Customer-managed keys also need tightly scoped KMS permissions and compatible key policy. AWS's managed aws/secretsmanager key cannot be used for every cross-account scenario.
• CloudTrail: AWS logs Secrets Manager API calls. Do not place sensitive data in secret names, descriptions, tags, rotation rule text, or other request parameters that AWS records as management events.
• Deferred operations: BatchGetSecretValue, GetRandomPassword, tag/untag after creation, resource-policy reads/writes/validation, cross-region replication, replica removal, rotation cancellation, and custom endpoints are intentionally not implemented.
• Provider verification boundary: deterministic tests cover validation, operation families, pagination, retry boundaries, confirmations, value/credential redaction, binary decoding, error normalization, registration, and metadata. Live AWS behavior remains unverified until an authorized AWS account and reviewed secret namespace, KMS policy, versions, and rotation function are supplied.
• Functional reference: n8n's AWS credential model and external secret store guidance inform reusable AWS credentials and secret-consumption ergonomics. AWS Secrets Manager API reference defines provider behavior. ValkyrAI adds the review, confirmation, redaction, and retry boundaries described above.
• Runtime boundary: merged source and published documentation do not update the deployed Workflow Studio catalog until a ValkyrAI backend release exposes AwsSecretsManagerModule through /v1/modules/metadata.

Related Documentation

• ExecModule catalog
• AWS Secrets Manager API reference
• AWS Systems Manager ExecModule
• AWS CloudFormation ExecModule
• Integration Account Concepts
• ExecModule Metadata Standards