> ## 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.

# Report supported optional endpoints

> Called when the connection is created and when a user clicks **Test
connection**. CloudCruise stores the result on the connection, so
after enabling an optional endpoint, click **Test connection** again.
A `200` proves that your endpoint is reachable and that signature
verification works.


> **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).
> * Sent when a user clicks **Connect**, and again on **Test connection**. A failing call means the connection is not created.
> * Return `item_listing: true` if you implement `POST /v1/items/list`. `password_write` and `item_search` are reserved: return `false` for both in this version.


## OpenAPI

````yaml custom-secret-provider-api/custom-secret-provider-api.yaml post /v1/capabilities
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/capabilities:
    post:
      summary: Report supported optional endpoints
      description: |
        Called when the connection is created and when a user clicks **Test
        connection**. CloudCruise stores the result on the connection, so
        after enabling an optional endpoint, click **Test connection** again.
        A `200` proves that your endpoint is reachable and that signature
        verification works.
      operationId: getCapabilities
      parameters:
        - $ref: '#/components/parameters/RequestId'
        - $ref: '#/components/parameters/ConnectionId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CapabilitiesRequest'
      responses:
        '200':
          description: Capabilities of this endpoint.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Capabilities'
        '400':
          $ref: '#/components/responses/InvalidRequest'
        '401':
          $ref: '#/components/responses/InvalidSignature'
        '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:
    CapabilitiesRequest:
      type: object
      description: Currently empty. Send `{}`; ignore unknown properties.
      additionalProperties: true
    Capabilities:
      type: object
      required:
        - item_listing
        - password_write
      properties:
        item_listing:
          type: boolean
          description: >-
            `true` if `POST /v1/items/list` is implemented. Without it, users
            type the `ref` when binding a credential.
        password_write:
          type: boolean
          description: 'Reserved: return `false` in this version.'
        item_search:
          type: boolean
          default: false
          description: 'Reserved: return `false` in this version.'
      examples:
        - item_listing: true
          password_write: false
          item_search: false
    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
    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.