openapi: 3.2.0
info:
  description: Use the Secret Retrieval API to retrieve secrets and secret versions from vaults. For more information, see [Managing Secrets](/Content/KeyManagement/Tasks/managingsecrets.htm).
  title: Vault Secret Retrieval Secrets API
  version: '20190301'
  x-provenance:
    method: harvested
    first_party: true
    publisher: Oracle
    source: https://docs.oracle.com/en-us/iaas/api/specs/d4bb34135ef3c27764d88e24ec1da31c44a09bbdc5f1c82e76cfb92b709257c3.yaml
    harvested: '2026-08-04'
    note: Published by Oracle as the contract for the Vault Secret Retrieval API OCI service and stored verbatim; API Evangelist added only this provenance block.
  x-evidence:
  - url: https://docs.oracle.com/en-us/iaas/api/specs/index.json
    what: Oracle's own index of every OCI service specification
  - url: https://docs.oracle.com/en-us/iaas/api/specs/d4bb34135ef3c27764d88e24ec1da31c44a09bbdc5f1c82e76cfb92b709257c3.yaml
    what: the harvested document for Vault Secret Retrieval API
servers:
- url: https://secrets.vaults.$region.oci.oraclecloud.com/20190301
tags:
- description: Use this API to retrieve secrets and secret versions from vaults.
  name: secrets
paths:
  /secretbundles/actions/getByName:
    post:
      description: 'Gets a secret bundle by secret name and vault ID, and secret version that matches either the specified `stage`, `secretVersionName`, or `versionNumber` parameter.

        If none of these parameters are provided, the bundle for the secret version marked as `CURRENT` is returned.

        '
      operationId: GetSecretBundleByName
      parameters:
      - $ref: '#/components/parameters/SecretNameQueryParam'
      - $ref: '#/components/parameters/VaultIdQueryParam'
      - $ref: '#/components/parameters/OpcRequestIdHeaderParam'
      - $ref: '#/components/parameters/SecretVersionNumberQueryParam'
      - $ref: '#/components/parameters/SecretVersionNameQueryParam'
      - $ref: '#/components/parameters/StageQueryParam'
      responses:
        200:
          description: A secret bundle.
          headers:
            opc-request-id:
              description: Unique Oracle-assigned identifier for the request. If you need to contact Oracle about a particular request, please provide the request ID.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SecretBundle'
        400:
          $ref: '#/components/responses/400'
        401:
          $ref: '#/components/responses/401'
        404:
          $ref: '#/components/responses/404'
        429:
          $ref: '#/components/responses/429'
        500:
          $ref: '#/components/responses/500'
        default:
          $ref: '#/components/responses/DefaultError'
      summary: Gets a secret bundle by secret name and vault ID.
      tags:
      - secrets
      x-example: 'POST /20190301/secretbundles/actions/getByName?secretName=<var>&lt;secret_name&gt;</var>&vaultId=<var>&lt;vault_Ocid&gt;</var>

        Host: <var>&lt;secretsEndpoint&gt;</var>

        <var>&lt;authorization and other headers&gt;</var>

        '
      x-related-resource: '#/definitions/SecretBundle'
  /secretbundles/{secretId}:
    get:
      description: 'Gets a secret bundle that matches either the specified `stage`, `secretVersionName`, or `versionNumber` parameter.

        If none of these parameters are provided, the bundle for the secret version marked as `CURRENT` will be returned.

        '
      operationId: GetSecretBundle
      parameters:
      - $ref: '#/components/parameters/OpcRequestIdHeaderParam'
      - $ref: '#/components/parameters/SecretIdRequiredPathParam'
      - $ref: '#/components/parameters/SecretVersionNumberQueryParam'
      - $ref: '#/components/parameters/SecretVersionNameQueryParam'
      - $ref: '#/components/parameters/StageQueryParam'
      responses:
        200:
          description: A secret bundle.
          headers:
            etag:
              description: For optimistic concurrency control. See `if-match`.
              schema:
                type: string
            opc-request-id:
              description: Unique Oracle-assigned identifier for the request. If you need to contact Oracle about a particular request, please provide the request ID.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SecretBundle'
        400:
          $ref: '#/components/responses/400'
        401:
          $ref: '#/components/responses/401'
        404:
          $ref: '#/components/responses/404'
        429:
          $ref: '#/components/responses/429'
        500:
          $ref: '#/components/responses/500'
        default:
          $ref: '#/components/responses/DefaultError'
      summary: Gets a secret bundle.
      tags:
      - secrets
      x-example: 'GET /20190301/secretbundles/<var>&lt;secret_OCID&gt;</var>

        Host: <var>&lt;secretsEndpoint&gt;</var>

        <var>&lt;authorization and other headers&gt;</var>

        '
  /secretbundles/{secretId}/versions:
    get:
      description: Lists all secret bundle versions for the specified secret.
      operationId: ListSecretBundleVersions
      parameters:
      - $ref: '#/components/parameters/OpcRequestIdHeaderParam'
      - $ref: '#/components/parameters/SecretIdRequiredPathParam'
      - $ref: '#/components/parameters/PaginationLimitQueryParam'
      - $ref: '#/components/parameters/PaginationTokenQueryParam'
      - $ref: '#/components/parameters/SortByQueryParam'
      - $ref: '#/components/parameters/SortOrderQueryParam'
      responses:
        200:
          description: A list of secret bundle version objects.
          headers:
            opc-next-page:
              description: 'For pagination of a list of items. When paging through a list, if this header appears in the response,

                then there are additional items still to get. Include this value as the `page` parameter for the

                subsequent GET request. For information about pagination, see

                [List Pagination](/Content/API/Concepts/usingapi.htm#List_Pagination).

                '
              schema:
                type: string
            opc-request-id:
              description: Unique Oracle-assigned identifier for the request. If you need to contact Oracle about a particular request, please provide the request ID.
              schema:
                type: string
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/SecretBundleVersionSummary'
                type: array
        400:
          $ref: '#/components/responses/400'
        401:
          $ref: '#/components/responses/401'
        404:
          $ref: '#/components/responses/404'
        429:
          $ref: '#/components/responses/429'
        500:
          $ref: '#/components/responses/500'
        default:
          $ref: '#/components/responses/DefaultError'
      summary: Lists all secret bundle versions.
      tags:
      - secrets
      x-example: 'GET /20190301/secretbundles/<var>&lt;secret_OCID&gt;</var>/versions

        Host: <var>&lt;secretsEndpoint&gt;</var>

        <var>&lt;authorization and other headers&gt;</var>

        '
      x-related-resource: '#/definitions/SecretBundleVersionSummary'
components:
  parameters:
    VaultIdQueryParam:
      description: The OCID of the vault that contains the secret.
      in: query
      name: vaultId
      required: true
      schema:
        type: string
        maxLength: 255
        minLength: 1
    SecretVersionNameQueryParam:
      description: The name of the secret. (This might be referred to as the name of the secret version. Names are unique across the different versions of a secret.)
      in: query
      name: secretVersionName
      required: false
      x-default-description: The default value is null.
      schema:
        type: string
    SortByQueryParam:
      description: 'The field to sort by. You can specify only one sort order. The default

        order for `VERSION_NUMBER` is descending.

        '
      in: query
      name: sortBy
      required: false
      schema:
        type: string
        enum:
        - VERSION_NUMBER
        default: VERSION_NUMBER
    PaginationTokenQueryParam:
      description: 'The value of the `opc-next-page` response header from the previous "List" call. For information about

        pagination, see [List Pagination](../../../#API/Concepts/usingapi.htm#List_Pagination).

        '
      in: query
      name: page
      x-default-description: The default value is null.
      schema:
        type: string
        maxLength: 512
        minLength: 1
    PaginationLimitQueryParam:
      description: 'The maximum number of items to return in a paginated "List" call. For information about pagination, see

        [List Pagination](../../../#API/Concepts/usingapi.htm#List_Pagination).

        '
      in: query
      name: limit
      schema:
        type: integer
        default: 10
        maximum: 1000
        minimum: 1
    SecretVersionNumberQueryParam:
      description: The version number of the secret.
      in: query
      name: versionNumber
      required: false
      x-default-description: The default value is `0`, which indicates a non-existent version.
      schema:
        type: integer
        format: int64
        default: 0
    SecretNameQueryParam:
      description: A user-friendly name for the secret. Secret names are unique within a vault. Secret names are case-sensitive.
      in: query
      name: secretName
      required: true
      schema:
        type: string
        maxLength: 255
        minLength: 1
    OpcRequestIdHeaderParam:
      description: Unique identifier for the request.
      in: header
      name: opc-request-id
      required: false
      schema:
        type: string
    StageQueryParam:
      description: The rotation state of the secret version.
      in: query
      name: stage
      required: false
      x-default-description: The default value is null.
      x-obmcs-inline-enum: true
      schema:
        type: string
        enum:
        - CURRENT
        - PENDING
        - LATEST
        - PREVIOUS
        - DEPRECATED
    SortOrderQueryParam:
      description: 'The sort order to use, either ascending (`ASC`) or descending (`DESC`).

        '
      in: query
      name: sortOrder
      required: false
      x-obmcs-inline-enum: true
      schema:
        type: string
        enum:
        - ASC
        - DESC
        default: DESC
    SecretIdRequiredPathParam:
      description: The OCID of the secret.
      in: path
      name: secretId
      required: true
      schema:
        type: string
  schemas:
    SecretBundleVersionSummary:
      description: 'The properties of the secret bundle. (Secret bundle version summary objects do not include the actual contents of the secret.)

        '
      properties:
        secretId:
          description: The OCID of the secret.
          type: string
        stages:
          description: A list of possible rotation states for the secret bundle.
          items:
            enum:
            - CURRENT
            - PENDING
            - LATEST
            - PREVIOUS
            - DEPRECATED
            type: string
            x-obmcs-inline-enum: true
          type: array
        timeCreated:
          description: The time when the secret bundle was created.
          format: date-time
          type: string
        timeOfDeletion:
          description: 'An optional property indicating when to delete the secret version, expressed in [RFC 3339](https://tools.ietf.org/html/rfc3339) timestamp format.

            Example: `2019-04-03T21:10:29.600Z`

            '
          format: date-time
          type: string
        timeOfExpiry:
          description: 'An optional property indicating when the secret version will expire, expressed in [RFC 3339](https://tools.ietf.org/html/rfc3339) timestamp format.

            Example: `2019-04-03T21:10:29.600Z`

            '
          format: date-time
          type: string
        versionName:
          description: 'The version name of the secret bundle, as provided when the secret was created or last rotated.

            '
          type: string
        versionNumber:
          description: The version number of the secret.
          format: int64
          type: integer
      required:
      - secretId
      - versionNumber
      type: object
      x-example: "[\n  {\n    \"secretId\": \"ocid1.vaultsecret.oc1.iad.exampleaz5qacpqadubrc4wwugrqmw5dnyzvcxwzds6er5enn2oamexample\",\n    \"timeCreated\": \"2020-03-18T16:51:38.851Z\",\n    \"versionNumber\": 1,\n    “versionName” : null,\n    “timeOfDeletion” : null,\n    “timeOfExpiry” : null,\n    “stages” : [ “CURRENT”, “LATEST” ]\n  }\n]\n"
    SecretBundle:
      description: 'The contents of the secret, properties of the secret (and secret version), and user-provided contextual metadata for the secret.

        '
      properties:
        metadata:
          additionalProperties:
            type: object
          description: 'Customer-provided contextual metadata for the secret.

            '
          type: object
        secretBundleContent:
          $ref: '#/components/schemas/SecretBundleContentDetails'
        secretId:
          description: The OCID of the secret.
          type: string
        stages:
          description: A list of possible rotation states for the secret version.
          items:
            enum:
            - CURRENT
            - PENDING
            - LATEST
            - PREVIOUS
            - DEPRECATED
            type: string
            x-obmcs-inline-enum: true
          type: array
        timeCreated:
          description: The time when the secret bundle was created.
          format: date-time
          type: string
        timeOfDeletion:
          description: 'An optional property indicating when to delete the secret version, expressed in [RFC 3339](https://tools.ietf.org/html/rfc3339) timestamp format.

            Example: `2019-04-03T21:10:29.600Z`

            '
          format: date-time
          type: string
        timeOfExpiry:
          description: 'An optional property indicating when the secret version will expire, expressed in [RFC 3339](https://tools.ietf.org/html/rfc3339) timestamp format.

            Example: `2019-04-03T21:10:29.600Z`

            '
          format: date-time
          type: string
        versionName:
          description: 'The name of the secret version. Labels are unique across the different versions of a particular secret.

            '
          type: string
        versionNumber:
          description: The version number of the secret.
          format: int64
          type: integer
      required:
      - secretId
      - versionNumber
      type: object
      x-example: "{\n  \"secretId\" : \"ocid1.vaultsecret.oc1.iad.exampleaz5qacpqadubrc4wwugrqmw5dnyzvcxwzds6er5enn2oamexample\",\n  \"timeCreated\" : \"2020-03-18T16:51:38.851Z\",\n  \"versionNumber\" : 1,\n  \"versionName\" : null,\n  \"secretBundleContent\" : {\n    \"contentType\" : \"BASE64\",\n    \"content\" : \"aGVsbG8h\"\n  },\n  \"timeOfDeletion\" : null,\n  \"timeOfExpiry\" : null,\n  \"stages\" : [ \"CURRENT\", \"LATEST\" ],\n  \"metadata\" : null\n}\n"
    SecretBundleContentDetails:
      description: The contents of the secret.
      discriminator:
        propertyName: contentType
      properties:
        contentType:
          description: The formatting type of the secret contents.
          enum:
          - BASE64
          type: string
          x-obmcs-inline-enum: true
      required:
      - contentType
      type: object
      x-example: "{\n  \"contentType\": \"BASE64\"\n}\n"
    Error:
      description: An error.
      properties:
        code:
          description: 'A short error code that defines the error, meant for programmatic parsing. See

            [API Errors](/Content/API/References/apierrors.htm).

            '
          type: string
        message:
          description: A human-readable error string.
          type: string
      required:
      - code
      - message
  responses:
    DefaultError:
      $ref: '#/components/responses/Error'
    Error:
      description: An error response.
      headers:
        opc-request-id:
          description: Unique identifier for the request.
          schema:
            type: string
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
x-obmcs-client-retries-enabled: true
x-oracle-package: com.oracle.bmc.swagger.vault