Amazon Secrets Manager API

openapi: 3.1.0
info:
  title: Amazon Secrets Manager API
  description: >-
    Amazon Secrets Manager helps you manage, retrieve, and rotate database
    credentials, API keys, and other secrets throughout their lifecycle. It
    provides centralized secrets management with built-in integration for Amazon
    RDS, Amazon Redshift, and Amazon DocumentDB, enabling automatic rotation of
    secrets without requiring application changes.
  version: '2017-10-17'
  contact:
    name: Kin Lane
    url: https://github.com/kinlane
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0
servers:
- url: https://secretsmanager.amazonaws.com
  description: Amazon Secrets Manager API
paths:
  /:
    post:
      operationId: CreateSecret
      summary: Amazon Secrets Manager Create Secret
      description: >-
        Creates a new secret. A secret can be a password, a set of credentials
        such as a user name and password, an OAuth token, or other secret
        information that you store in an encrypted form in Secrets Manager.
      parameters:
      - name: X-Amz-Target
        in: header
        required: true
        schema:
          type: string
          enum:
          - secretsmanager.CreateSecret
      requestBody:
        required: true
        content:
          application/x-amz-json-1.1:
            schema:
              $ref: '#/components/schemas/CreateSecretRequest'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateSecretResponse'
              examples:
                CreateSecret200Example:
                  summary: Default CreateSecret 200 response
                  x-microcks-default: true
                  value:
                    ARN: arn:aws:secretsmanager:us-east-1:123456789012:secret:MySecret-a1b2c3
                    Name: MySecret
                    VersionId: a1b2c3d4-e5f6-7890-abcd-ef1234567890
      tags:
      - Secrets
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /#GetSecretValue:
    post:
      operationId: GetSecretValue
      summary: Amazon Secrets Manager Get Secret Value
      description: >-
        Retrieves the contents of the encrypted fields SecretString or
        SecretBinary from the specified version of a secret.
      parameters:
      - name: X-Amz-Target
        in: header
        required: true
        schema:
          type: string
          enum:
          - secretsmanager.GetSecretValue
      requestBody:
        required: true
        content:
          application/x-amz-json-1.1:
            schema:
              $ref: '#/components/schemas/GetSecretValueRequest'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetSecretValueResponse'
              examples:
                GetSecretValue200Example:
                  summary: Default GetSecretValue 200 response
                  x-microcks-default: true
                  value:
                    ARN: arn:aws:secretsmanager:us-east-1:123456789012:secret:MySecret-a1b2c3
                    Name: MySecret
                    VersionId: a1b2c3d4-e5f6-7890-abcd-ef1234567890
      tags:
      - Secrets
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /#PutSecretValue:
    post:
      operationId: PutSecretValue
      summary: Amazon Secrets Manager Put Secret Value
      description: >-
        Creates a new version with a new encrypted secret value and attaches it
        to the secret. The version can contain a new SecretString value or a new
        SecretBinary value.
      parameters:
      - name: X-Amz-Target
        in: header
        required: true
        schema:
          type: string
          enum:
          - secretsmanager.PutSecretValue
      requestBody:
        required: true
        content:
          application/x-amz-json-1.1:
            schema:
              $ref: '#/components/schemas/PutSecretValueRequest'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PutSecretValueResponse'
              examples:
                PutSecretValue200Example:
                  summary: Default PutSecretValue 200 response
                  x-microcks-default: true
                  value:
                    ARN: arn:aws:secretsmanager:us-east-1:123456789012:secret:MySecret-a1b2c3
                    Name: MySecret
                    VersionId: a1b2c3d4-e5f6-7890-abcd-ef1234567890
      tags:
      - Secrets
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /#UpdateSecret:
    post:
      operationId: UpdateSecret
      summary: Amazon Secrets Manager Update Secret
      description: >-
        Modifies the details of a secret, including metadata and the secret
        value. To change the secret value, you can also use PutSecretValue.
      parameters:
      - name: X-Amz-Target
        in: header
        required: true
        schema:
          type: string
          enum:
          - secretsmanager.UpdateSecret
      requestBody:
        required: true
        content:
          application/x-amz-json-1.1:
            schema:
              $ref: '#/components/schemas/UpdateSecretRequest'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpdateSecretResponse'
              examples:
                UpdateSecret200Example:
                  summary: Default UpdateSecret 200 response
                  x-microcks-default: true
                  value:
                    ARN: arn:aws:secretsmanager:us-east-1:123456789012:secret:MySecret-a1b2c3
                    Name: MySecret
                    VersionId: a1b2c3d4-e5f6-7890-abcd-ef1234567890
      tags:
      - Secrets
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /#DeleteSecret:
    post:
      operationId: DeleteSecret
      summary: Amazon Secrets Manager Delete Secret
      description: >-
        Deletes a secret and all of its versions. You can specify a recovery
        window during which you can restore the secret. The minimum recovery
        window is 7 days. The default recovery window is 30 days.
      parameters:
      - name: X-Amz-Target
        in: header
        required: true
        schema:
          type: string
          enum:
          - secretsmanager.DeleteSecret
      requestBody:
        required: true
        content:
          application/x-amz-json-1.1:
            schema:
              $ref: '#/components/schemas/DeleteSecretRequest'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteSecretResponse'
              examples:
                DeleteSecret200Example:
                  summary: Default DeleteSecret 200 response
                  x-microcks-default: true
                  value:
                    ARN: arn:aws:secretsmanager:us-east-1:123456789012:secret:MySecret-a1b2c3
                    Name: MySecret
                    VersionId: a1b2c3d4-e5f6-7890-abcd-ef1234567890
      tags:
      - Secrets
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /#ListSecrets:
    post:
      operationId: ListSecrets
      summary: Amazon Secrets Manager List Secrets
      description: >-
        Lists the secrets that are stored by Secrets Manager in the Amazon Web
        Services account, not including secrets that are marked for deletion.
      parameters:
      - name: X-Amz-Target
        in: header
        required: true
        schema:
          type: string
          enum:
          - secretsmanager.ListSecrets
      requestBody:
        required: true
        content:
          application/x-amz-json-1.1:
            schema:
              $ref: '#/components/schemas/ListSecretsRequest'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListSecretsResponse'
              examples:
                ListSecrets200Example:
                  summary: Default ListSecrets 200 response
                  x-microcks-default: true
                  value:
                    ARN: arn:aws:secretsmanager:us-east-1:123456789012:secret:MySecret-a1b2c3
                    Name: MySecret
                    VersionId: a1b2c3d4-e5f6-7890-abcd-ef1234567890
      tags:
      - Secrets
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /#DescribeSecret:
    post:
      operationId: DescribeSecret
      summary: Amazon Secrets Manager Describe Secret
      description: >-
        Retrieves the details of a secret. It does not include the encrypted
        secret value. Secrets Manager only returns fields that have a value in
        the response.
      parameters:
      - name: X-Amz-Target
        in: header
        required: true
        schema:
          type: string
          enum:
          - secretsmanager.DescribeSecret
      requestBody:
        required: true
        content:
          application/x-amz-json-1.1:
            schema:
              $ref: '#/components/schemas/DescribeSecretRequest'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DescribeSecretResponse'
              examples:
                DescribeSecret200Example:
                  summary: Default DescribeSecret 200 response
                  x-microcks-default: true
                  value:
                    ARN: arn:aws:secretsmanager:us-east-1:123456789012:secret:MySecret-a1b2c3
                    Name: MySecret
                    VersionId: a1b2c3d4-e5f6-7890-abcd-ef1234567890
      tags:
      - Secrets
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /#RotateSecret:
    post:
      operationId: RotateSecret
      summary: Amazon Secrets Manager Rotate Secret
      description: >-
        Configures and starts the asynchronous process of rotating the secret.
        If you include the configuration parameters, the operation sets the
        values for the secret and then immediately starts a rotation.
      parameters:
      - name: X-Amz-Target
        in: header
        required: true
        schema:
          type: string
          enum:
          - secretsmanager.RotateSecret
      requestBody:
        required: true
        content:
          application/x-amz-json-1.1:
            schema:
              $ref: '#/components/schemas/RotateSecretRequest'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RotateSecretResponse'
              examples:
                RotateSecret200Example:
                  summary: Default RotateSecret 200 response
                  x-microcks-default: true
                  value:
                    ARN: arn:aws:secretsmanager:us-east-1:123456789012:secret:MySecret-a1b2c3
                    Name: MySecret
                    VersionId: a1b2c3d4-e5f6-7890-abcd-ef1234567890
      tags:
      - Rotation
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /#RestoreSecret:
    post:
      operationId: RestoreSecret
      summary: Amazon Secrets Manager Restore Secret
      description: >-
        Cancels the scheduled deletion of a secret by removing the DeletedDate
        time stamp. You can access a secret again after it has been restored.
      parameters:
      - name: X-Amz-Target
        in: header
        required: true
        schema:
          type: string
          enum:
          - secretsmanager.RestoreSecret
      requestBody:
        required: true
        content:
          application/x-amz-json-1.1:
            schema:
              $ref: '#/components/schemas/RestoreSecretRequest'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RestoreSecretResponse'
              examples:
                RestoreSecret200Example:
                  summary: Default RestoreSecret 200 response
                  x-microcks-default: true
                  value:
                    ARN: arn:aws:secretsmanager:us-east-1:123456789012:secret:MySecret-a1b2c3
                    Name: MySecret
                    VersionId: a1b2c3d4-e5f6-7890-abcd-ef1234567890
      tags:
      - Secrets
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /#TagResource:
    post:
      operationId: TagResource
      summary: Amazon Secrets Manager Tag Resource
      description: >-
        Attaches tags to a secret. Tags consist of a key name and a value. Tags
        are part of the secret's metadata and are not associated with specific
        versions of the secret.
      parameters:
      - name: X-Amz-Target
        in: header
        required: true
        schema:
          type: string
          enum:
          - secretsmanager.TagResource
      requestBody:
        required: true
        content:
          application/x-amz-json-1.1:
            schema:
              $ref: '#/components/schemas/TagResourceRequest'
      responses:
        '200':
          description: Successful response
      tags: []
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /#UntagResource:
    post:
      operationId: UntagResource
      summary: Amazon Secrets Manager Untag Resource
      description: >-
        Removes specific tags from a secret. This operation is idempotent. If a
        requested tag is not attached to the secret, no error is returned.
      parameters:
      - name: X-Amz-Target
        in: header
        required: true
        schema:
          type: string
          enum:
          - secretsmanager.UntagResource
      requestBody:
        required: true
        content:
          application/x-amz-json-1.1:
            schema:
              $ref: '#/components/schemas/UntagResourceRequest'
      responses:
        '200':
          description: Successful response
      tags: []
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /#GetRandomPassword:
    post:
      operationId: GetRandomPassword
      summary: Amazon Secrets Manager Get Random Password
      description: >-
        Generates a random password. You can use this operation to generate a
        password for a new secret or to change the value of an existing secret.
      parameters:
      - name: X-Amz-Target
        in: header
        required: true
        schema:
          type: string
          enum:
          - secretsmanager.GetRandomPassword
      requestBody:
        required: true
        content:
          application/x-amz-json-1.1:
            schema:
              $ref: '#/components/schemas/GetRandomPasswordRequest'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetRandomPasswordResponse'
              examples:
                GetRandomPassword200Example:
                  summary: Default GetRandomPassword 200 response
                  x-microcks-default: true
                  value:
                    ARN: arn:aws:secretsmanager:us-east-1:123456789012:secret:MySecret-a1b2c3
                    Name: MySecret
                    VersionId: a1b2c3d4-e5f6-7890-abcd-ef1234567890
      tags:
      - Passwords
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  schemas:
    Secret:
      type: object
      properties:
        ARN:
          type: string
          description: The ARN of the secret.
        Name:
          type: string
          description: The friendly name of the secret.
        Description:
          type: string
          description: The description of the secret.
        KmsKeyId:
          type: string
          description: The ARN of the KMS key used to encrypt the secret.
        RotationEnabled:
          type: boolean
          description: Whether rotation is enabled for this secret.
        RotationLambdaARN:
          type: string
          description: The ARN of the Lambda function that rotates the secret.
        RotationRules:
          $ref: '#/components/schemas/RotationRules'
        LastRotatedDate:
          type: string
          format: date-time
          description: The most recent date and time that rotation was triggered.
        LastChangedDate:
          type: string
          format: date-time
          description: The last date and time that this secret was modified.
        LastAccessedDate:
          type: string
          format: date-time
          description: The last date that this secret was accessed.
        DeletedDate:
          type: string
          format: date-time
          description: The date and time the deletion of the secret occurred.
        Tags:
          type: array
          items:
            $ref: '#/components/schemas/Tag'
          description: The list of tags attached to the secret.
        SecretVersionsToStages:
          type: object
          additionalProperties:
            type: array
            items:
              type: string
          description: A list of the versions of the secret that have staging labels attached.
        OwningService:
          type: string
          description: The name of the service that created this secret.
        CreatedDate:
          type: string
          format: date-time
          description: The date and time when the secret was created.
        PrimaryRegion:
          type: string
          description: The Region the secret is in.

    SecretValue:
      type: object
      properties:
        ARN:
          type: string
          description: The ARN of the secret.
        Name:
          type: string
          description: The friendly name of the secret.
        VersionId:
          type: string
          description: The unique identifier of this version of the secret.
        SecretBinary:
          type: string
          format: byte
          description: The decrypted secret value in binary format.
        SecretString:
          type: string
          description: The decrypted secret value in string format.
        VersionStages:
          type: array
          items:
            type: string
          description: A list of the staging labels that are attached to this version.
        CreatedDate:
          type: string
          format: date-time
          description: The date and time that this version of the secret was created.

    RotationRules:
      type: object
      properties:
        AutomaticallyAfterDays:
          type: integer
          description: The number of days between automatic scheduled rotations.
        Duration:
          type: string
          description: The length of the rotation window in hours.
        ScheduleExpression:
          type: string
          description: A cron or rate expression that defines the schedule for rotation.

    Tag:
      type: object
      properties:
        Key:
          type: string
          description: The key identifier or name of the tag.
        Value:
          type: string
          description: The string value associated with the key of the tag.

    CreateSecretRequest:
      type: object
      required:
      - Name
      properties:
        Name:
          type: string
          description: The name of the new secret.
        Description:
          type: string
          description: The description of the secret.
        KmsKeyId:
          type: string
          description: The ARN, key ID, or alias of the KMS key to encrypt the secret.
        SecretBinary:
          type: string
          format: byte
          description: The binary data to encrypt and store in the secret.
        SecretString:
          type: string
          description: The text data to encrypt and store in the secret.
        Tags:
          type: array
          items:
            $ref: '#/components/schemas/Tag'
        ClientRequestToken:
          type: string
          description: A unique identifier for the new version of the secret.

    CreateSecretResponse:
      type: object
      properties:
        ARN:
          type: string
        Name:
          type: string
        VersionId:
          type: string

    GetSecretValueRequest:
      type: object
      required:
      - SecretId
      properties:
        SecretId:
          type: string
          description: The ARN or name of the secret to retrieve.
        VersionId:
          type: string
          description: The unique identifier of the version of the secret to retrieve.
        VersionStage:
          type: string
          description: The staging label of the version of the secret to retrieve.

    GetSecretValueResponse:
      $ref: '#/components/schemas/SecretValue'

    PutSecretValueRequest:
      type: object
      required:
      - SecretId
      properties:
        SecretId:
          type: string
          description: The ARN or name of the secret to update.
        SecretBinary:
          type: string
          format: byte
        SecretString:
          type: string
        ClientRequestToken:
          type: string
        VersionStages:
          type: array
          items:
            type: string

    PutSecretValueResponse:
      type: object
      properties:
        ARN:
          type: string
        Name:
          type: string
        VersionId:
          type: string
        VersionStages:
          type: array
          items:
            type: string

    UpdateSecretRequest:
      type: object
      required:
      - SecretId
      properties:
        SecretId:
          type: string
        Description:
          type: string
        KmsKeyId:
          type: string
        SecretBinary:
          type: string
          format: byte
        SecretString:
          type: string
        ClientRequestToken:
          type: string

    UpdateSecretResponse:
      type: object
      properties:
        ARN:
          type: string
        Name:
          type: string
        VersionId:
          type: string

    DeleteSecretRequest:
      type: object
      required:
      - SecretId
      properties:
        SecretId:
          type: string
          description: The ARN or name of the secret to delete.
        RecoveryWindowInDays:
          type: integer
          description: The number of days that Secrets Manager waits before permanent deletion.
        ForceDeleteWithoutRecovery:
          type: boolean
          description: Use this parameter with caution. It permanently deletes the secret without any recovery window.

    DeleteSecretResponse:
      type: object
      properties:
        ARN:
          type: string
        Name:
          type: string
        DeletionDate:
          type: string
          format: date-time

    ListSecretsRequest:
      type: object
      properties:
        MaxResults:
          type: integer
          description: The maximum number of results to include in the response.
        NextToken:
          type: string
          description: A token for pagination.
        Filters:
          type: array
          items:
            type: object
            properties:
              Key:
                type: string
                enum:
                - description
                - name
                - tag-key
                - tag-value
                - primary-region
                - owning-service
                - all
              Values:
                type: array
                items:
                  type: string
        SortOrder:
          type: string
          enum:
          - asc
          - desc

    ListSecretsResponse:
      type: object
      properties:
        SecretList:
          type: array
          items:
            $ref: '#/components/schemas/Secret'
        NextToken:
          type: string

    DescribeSecretRequest:
      type: object
      required:
      - SecretId
      properties:
        SecretId:
          type: string
          description: The ARN or name of the secret to describe.

    DescribeSecretResponse:
      $ref: '#/components/schemas/Secret'

    RotateSecretRequest:
      type: object
      required:
      - SecretId
      properties:
        SecretId:
          type: string
          description: The ARN or name of the secret to rotate.
        ClientRequestToken:
          type: string
        RotationLambdaARN:
          type: string
          description: The ARN of the Lambda rotation function.
        RotationRules:
          $ref: '#/components/schemas/RotationRules'
        RotateImmediately:
          type: boolean
          description: Whether to rotate the secret immediately.

    RotateSecretResponse:
      type: object
      properties:
        ARN:
          type: string
        Name:
          type: string
        VersionId:
          type: string

    RestoreSecretRequest:
      type: object
      required:
      - SecretId
      properties:
        SecretId:
          type: string
          description: The ARN or name of the secret to restore.

    RestoreSecretResponse:
      type: object
      properties:
        ARN:
          type: string
        Name:
          type: string

    TagResourceRequest:
      type: object
      required:
      - SecretId
      - Tags
      properties:
        SecretId:
          type: string
          description: The ARN or name of the secret to tag.
        Tags:
          type: array
          items:
            $ref: '#/components/schemas/Tag'

    UntagResourceRequest:
      type: object
      required:
      - SecretId
      - TagKeys
      properties:
        SecretId:
          type: string
          description: The ARN or name of the secret to untag.
        TagKeys:
          type: array
          items:
            type: string
          description: A list of tag key names to remove from the secret.

    GetRandomPasswordRequest:
      type: object
      properties:
        PasswordLength:
          type: integer
          description: The length of the password. Default is 32 characters.
        ExcludeCharacters:
          type: string
          description: A string of characters to exclude from the password.
        ExcludeNumbers:
          type: boolean
        ExcludePunctuation:
          type: boolean
        ExcludeUppercase:
          type: boolean
        ExcludeLowercase:
          type: boolean
        IncludeSpace:
          type: boolean
        RequireEachIncludedType:
          type: boolean

    GetRandomPasswordResponse:
      type: object
      properties:
        RandomPassword:
          type: string
          description: A string with the password.
tags:
- name: Passwords
  description: Operations for generating passwords.
- name: Rotation
  description: Operations for rotating secrets.
- name: Secrets
  description: Operations for managing secrets.