generated: '2026-06-20'
method: derived
source: >-
  openapi/amazon-secrets-manager-openapi.yml plus the AWS Secrets Manager API
  reference and AWS query-protocol conventions. Cross-cutting request/response
  semantics that apply to every operation.
base_url: https://secretsmanager.{region}.amazonaws.com
api_style: >-
  AWS JSON 1.1 query protocol over HTTPS — POST requests with a JSON body and an
  X-Amz-Target header that names the action; JSON responses.

authentication:
  scheme: AWS Signature Version 4 (SigV4)
  detail: authentication/amazon-secrets-manager-authentication.yml
  docs: https://docs.aws.amazon.com/general/latest/gr/signature-version-4.html

operation_dispatch:
  mechanism: X-Amz-Target header
  detail: >-
    The operation is selected by the X-Amz-Target header (e.g.
    secretsmanager.GetSecretValue) rather than by the URL path; all requests POST
    to "/".

idempotency:
  supported: true
  mechanism: ClientRequestToken request field
  applies_to: CreateSecret, PutSecretValue, UpdateSecret, RotateSecret
  detail: >-
    A client-generated ClientRequestToken (UUID) makes create/put/rotate
    operations idempotent — replaying with the same token and body returns the
    original result instead of creating a duplicate version.

pagination:
  style: cursor
  request_params:
    MaxResults: Maximum number of results per page.
    NextToken: Opaque token returned by the previous page.
  response_fields:
    NextToken: Present when more results are available; pass it to fetch the next page.
  applies_to: [ListSecrets, ListSecretVersionIds, BatchGetSecretValue]

filtering:
  supported: true
  detail: >-
    ListSecrets accepts Filters[] keyed by description, name, tag-key, tag-value,
    primary-region, owning-service, or all, plus a SortOrder (asc|desc).

metadata:
  supported: true
  mechanism: Tags (Key/Value pairs) attached to secrets via TagResource/UntagResource.

request_tracing:
  request_id: >-
    Every response carries an x-amzn-RequestId header; include it when contacting
    AWS Support. Full request auditing is available via AWS CloudTrail.

versioning:
  detail: lifecycle/amazon-secrets-manager-lifecycle.yml
  scheme: date-stamped API version (2017-10-17), pinned per SDK.

secret_versioning:
  detail: >-
    A secret holds multiple versions distinguished by VersionId, with staging
    labels (VersionStages, e.g. AWSCURRENT / AWSPENDING / AWSPREVIOUS) that enable
    zero-downtime rotation.

error_envelope:
  detail: errors/amazon-secrets-manager-problem-types.yml
  format: >-
    application/x-amz-json-1.1 with __type (exception name) and message fields;
    HTTP 4xx/5xx status.

rate_limit_signaling:
  detail: rate-limits/amazon-secrets-manager-rate-limits.yml
  mechanism: >-
    Throttling is signaled with a ThrottlingException; clients should retry with
    exponential backoff and jitter (the AWS SDKs do this automatically).