> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cloudcruise.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Return the secret values of one item

> Return the fields the item has. Omit a field (or return `null`) when
the item does not have it; an empty string is treated the same as
absent. A response with none of the three fields is treated as an
error ("credential resolved to empty"), handled like the errors in
the table above.


> **Note:**
>
> * Your endpoint, not CloudCruise, hosts this operation. Every request is signed; see [request authentication](https://docs.cloudcruise.com/integrations/custom-provider.md#request-authentication).
> * `totp_seed` is the TOTP secret, not a one-time code. See [Two-Factor Authentication](https://docs.cloudcruise.com/integrations/custom-provider.md#two-factor-authentication-totp).
> * Results are cached for the connection's cache duration; see [Caching and call volume](https://docs.cloudcruise.com/integrations/custom-provider.md#caching-and-call-volume).


## OpenAPI

````yaml custom-secret-provider-api/custom-secret-provider-api.yaml post /v1/items/resolve
openapi: 3.1.0
info:
  title: CloudCruise Custom Secret Provider API
  version: 1.0.0
  summary: >-
    The API your password manager exposes so CloudCruise can resolve vault
    credentials from it at run time.
  description: >
    > **Stable.** The endpoints below will not change incompatibly within `v1`.

    > Additional endpoints and optional fields may be added in

    > backwards-compatible ways.


    Implement this API in front of your own password manager to use it with

    CloudCruise the same way as the built-in 1Password integration. You host

    the API; CloudCruise calls it.


    All endpoints are `POST` with a JSON body, including read operations. Item

    references travel in the body, never in the URL, so they are never altered

    by URL encoding and do not appear in access logs.


    | Endpoint | Required | Used for |

    | --- | --- | --- |

    | `POST /v1/capabilities` | yes | Connection test; reports whether you
    implement item listing |

    | `POST /v1/items/resolve` | yes | Fetching the secret values of one item |

    | `POST /v1/items/describe` | yes | Showing the bound item's name in the
    dashboard |

    | `POST /v1/items/list` | if `item_listing` | Letting users pick an item
    instead of typing its `ref` |


    ## Request authentication


    Every request is signed with HMAC-SHA256 using the connection's signing

    secret and carries the `X-CloudCruise-Timestamp`,

    `X-CloudCruise-Request-Id`, `X-CloudCruise-Connection-Id` and

    `X-CloudCruise-Signature` headers. The signed string, the verification

    rules, a Node.js example and a test vector are in the

    [Custom provider
    guide](https://docs.cloudcruise.com/integrations/custom-provider).
servers:
  - url: '{baseUrl}'
    description: The HTTPS base URL you configure on the CloudCruise connection.
    variables:
      baseUrl:
        default: https://pm.example.com/cloudcruise
security:
  - cloudcruiseSignature: []
    cloudcruiseTimestamp: []
paths:
  /v1/items/resolve:
    post:
      summary: Return the secret values of one item
      description: |
        Return the fields the item has. Omit a field (or return `null`) when
        the item does not have it; an empty string is treated the same as
        absent. A response with none of the three fields is treated as an
        error ("credential resolved to empty"), handled like the errors in
        the table above.
      operationId: resolveItem
      parameters:
        - $ref: '#/components/parameters/RequestId'
        - $ref: '#/components/parameters/ConnectionId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ItemRequest'
      responses:
        '200':
          description: The item's secret values.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResolvedItem'
        '400':
          $ref: '#/components/responses/InvalidRequest'
        '401':
          $ref: '#/components/responses/InvalidSignature'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/ItemNotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        5XX:
          $ref: '#/components/responses/ServerError'
components:
  parameters:
    RequestId:
      name: X-CloudCruise-Request-Id
      in: header
      required: true
      description: Unique per request; never reused, including across retries.
      schema:
        type: string
        format: uuid
    ConnectionId:
      name: X-CloudCruise-Connection-Id
      in: header
      required: true
      description: The CloudCruise connection id. Not secret.
      schema:
        type: string
        format: uuid
  schemas:
    ItemRequest:
      type: object
      required:
        - ref
      properties:
        ref:
          $ref: '#/components/schemas/Ref'
      examples:
        - ref: prod/acme-portal/login
    ResolvedItem:
      type: object
      properties:
        user_name:
          type:
            - string
            - 'null'
          maxLength: 1024
        password:
          type:
            - string
            - 'null'
          maxLength: 4096
        totp_seed:
          type:
            - string
            - 'null'
          maxLength: 2048
          description: Base32 TOTP secret or `otpauth://totp/...` URI. Not a one-time code.
      examples:
        - user_name: automation@acme.com
          password: correct-horse-battery-staple
          totp_seed: JBSWY3DPEHPK3PXP
    Ref:
      type: string
      minLength: 1
      maxLength: 512
      pattern: ^[\x20-\x7E]+$
      description: Your identifier for one item. Opaque to CloudCruise.
      examples:
        - prod/acme-portal/login
    Error:
      type: object
      required:
        - error
      properties:
        error:
          type: object
          required:
            - code
            - message
          properties:
            code:
              type: string
              maxLength: 100
              description: |
                Known values: `invalid_request`, `invalid_signature`,
                `forbidden`, `item_not_found`, `rate_limited`,
                `internal_error`.
                CloudCruise handles an
                unknown code according to the HTTP status.
              examples:
                - item_not_found
            message:
              type: string
              maxLength: 1000
              description: Shown to CloudCruise users. Never include secret values.
  responses:
    InvalidRequest:
      description: The request is malformed.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: invalid_request
              message: ref is required
    InvalidSignature:
      description: Signature, timestamp or signing-secret check failed.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: invalid_signature
              message: Signature verification failed
    Forbidden:
      description: The signature is valid, but this connection may not access the item.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: forbidden
              message: Connection has read-only access to this item
    ItemNotFound:
      description: No item with this ref.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: item_not_found
              message: No item prod/acme-portal/login
    RateLimited:
      description: >-
        Too many requests. CloudCruise retries, honouring `Retry-After` up to 10
        seconds.
      headers:
        Retry-After:
          description: Seconds to wait before retrying.
          schema:
            type: integer
            minimum: 0
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    ServerError:
      description: >-
        Your service failed. CloudCruise retries, then fails the run as "secret
        provider unavailable".
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    cloudcruiseSignature:
      type: apiKey
      in: header
      name: X-CloudCruise-Signature
      description: |
        `v1=<hex HMAC-SHA256>`, possibly several comma-separated values during
        a secret rotation. See **Request authentication** above.
    cloudcruiseTimestamp:
      type: apiKey
      in: header
      name: X-CloudCruise-Timestamp
      description: >-
        Unix time in seconds, part of the signed string. Reject if more than 300
        seconds off.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.