Stacklok secrets API

openapi: 3.1.0
info:
  contact:
    url: https://github.com/stacklok/toolhive
  description: 'API for accessing MCP server registry data and deployed server information

    This API provides endpoints to query the MCP (Model Context Protocol) server registry,

    get information about available servers, and check the status of deployed servers.


    Authentication is required by default. Use Bearer token authentication with a valid

    OAuth/OIDC access token. The /.well-known/oauth-protected-resource endpoint provides

    OAuth discovery metadata (RFC 9728).'
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
  title: ToolHive Registry clients secrets API
  version: '0.1'
tags:
- name: secrets
paths:
  /api/v1beta/secrets:
    post:
      description: Setup the secrets provider with the specified type and configuration.
      requestBody:
        content:
          application/json:
            schema:
              oneOf:
              - type: object
              - $ref: '#/components/schemas/pkg_api_v1.setupSecretsRequest'
                description: Setup secrets provider request
                summary: request
        description: Setup secrets provider request
        required: true
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/pkg_api_v1.setupSecretsResponse'
          description: Created
        '400':
          content:
            application/json:
              schema:
                type: string
          description: Bad Request
        '500':
          content:
            application/json:
              schema:
                type: string
          description: Internal Server Error
      summary: Setup or reconfigure secrets provider
      tags:
      - secrets
  /api/v1beta/secrets/default:
    get:
      description: Get details of the default secrets provider
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/pkg_api_v1.getSecretsProviderResponse'
          description: OK
        '404':
          content:
            application/json:
              schema:
                type: string
          description: Not Found - Provider not setup
        '500':
          content:
            application/json:
              schema:
                type: string
          description: Internal Server Error
      summary: Get secrets provider details
      tags:
      - secrets
  /api/v1beta/secrets/default/keys:
    get:
      description: Get a list of all secret keys from the default provider
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/pkg_api_v1.listSecretsResponse'
          description: OK
        '404':
          content:
            application/json:
              schema:
                type: string
          description: Not Found - Provider not setup
        '405':
          content:
            application/json:
              schema:
                type: string
          description: Method Not Allowed - Provider doesn't support listing
        '500':
          content:
            application/json:
              schema:
                type: string
          description: Internal Server Error
      summary: List secrets
      tags:
      - secrets
    post:
      description: Create a new secret in the default provider (encrypted provider only)
      requestBody:
        content:
          application/json:
            schema:
              oneOf:
              - type: object
              - $ref: '#/components/schemas/pkg_api_v1.createSecretRequest'
                description: Create secret request
                summary: request
        description: Create secret request
        required: true
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/pkg_api_v1.createSecretResponse'
          description: Created
        '400':
          content:
            application/json:
              schema:
                type: string
          description: Bad Request
        '404':
          content:
            application/json:
              schema:
                type: string
          description: Not Found - Provider not setup
        '405':
          content:
            application/json:
              schema:
                type: string
          description: Method Not Allowed - Provider doesn't support writing
        '409':
          content:
            application/json:
              schema:
                type: string
          description: Conflict - Secret already exists
        '500':
          content:
            application/json:
              schema:
                type: string
          description: Internal Server Error
      summary: Create a new secret
      tags:
      - secrets
  /api/v1beta/secrets/default/keys/{key}:
    delete:
      description: Delete a secret from the default provider (encrypted provider only)
      parameters:
      - description: Secret key
        in: path
        name: key
        required: true
        schema:
          type: string
      responses:
        '204':
          content:
            application/json:
              schema:
                type: string
          description: No Content
        '404':
          content:
            application/json:
              schema:
                type: string
          description: Not Found - Provider not setup or secret not found
        '405':
          content:
            application/json:
              schema:
                type: string
          description: Method Not Allowed - Provider doesn't support deletion
        '500':
          content:
            application/json:
              schema:
                type: string
          description: Internal Server Error
      summary: Delete a secret
      tags:
      - secrets
    put:
      description: Update an existing secret in the default provider (encrypted provider only)
      parameters:
      - description: Secret key
        in: path
        name: key
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              oneOf:
              - type: object
              - $ref: '#/components/schemas/pkg_api_v1.updateSecretRequest'
                description: Update secret request
                summary: request
        description: Update secret request
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/pkg_api_v1.updateSecretResponse'
          description: OK
        '400':
          content:
            application/json:
              schema:
                type: string
          description: Bad Request
        '404':
          content:
            application/json:
              schema:
                type: string
          description: Not Found - Provider not setup or secret not found
        '405':
          content:
            application/json:
              schema:
                type: string
          description: Method Not Allowed - Provider doesn't support writing
        '500':
          content:
            application/json:
              schema:
                type: string
          description: Internal Server Error
      summary: Update a secret
      tags:
      - secrets
components:
  schemas:
    pkg_api_v1.providerCapabilitiesResponse:
      description: Capabilities of the secrets provider
      properties:
        can_cleanup:
          description: Whether the provider can cleanup all secrets
          type: boolean
        can_delete:
          description: Whether the provider can delete secrets
          type: boolean
        can_list:
          description: Whether the provider can list secrets
          type: boolean
        can_read:
          description: Whether the provider can read secrets
          type: boolean
        can_write:
          description: Whether the provider can write secrets
          type: boolean
      type: object
    pkg_api_v1.setupSecretsRequest:
      description: Request to setup a secrets provider
      properties:
        password:
          description: 'Password for encrypted provider (optional, can be set via environment variable)

            TODO Review environment variable for this'
          type: string
        provider_type:
          description: Type of the secrets provider (encrypted, 1password, environment)
          type: string
      type: object
    pkg_api_v1.createSecretRequest:
      description: Request to create a new secret
      properties:
        key:
          description: Secret key name
          type: string
        value:
          description: Secret value
          type: string
      type: object
    pkg_api_v1.updateSecretRequest:
      description: Request to update an existing secret
      properties:
        value:
          description: New secret value
          type: string
      type: object
    pkg_api_v1.listSecretsResponse:
      description: Response containing a list of secret keys
      properties:
        keys:
          description: List of secret keys
          items:
            $ref: '#/components/schemas/pkg_api_v1.secretKeyResponse'
          type: array
          uniqueItems: false
      type: object
    pkg_api_v1.secretKeyResponse:
      description: Secret key information
      properties:
        description:
          description: Optional description of the secret
          type: string
        key:
          description: Secret key name
          type: string
      type: object
    pkg_api_v1.updateSecretResponse:
      description: Response after updating a secret
      properties:
        key:
          description: Secret key that was updated
          type: string
        message:
          description: Success message
          type: string
      type: object
    pkg_api_v1.setupSecretsResponse:
      description: Response after initializing a secrets provider
      properties:
        message:
          description: Success message
          type: string
        provider_type:
          description: Type of the secrets provider that was setup
          type: string
      type: object
    pkg_api_v1.getSecretsProviderResponse:
      description: Response containing secrets provider details
      properties:
        capabilities:
          $ref: '#/components/schemas/pkg_api_v1.providerCapabilitiesResponse'
        name:
          description: Name of the secrets provider
          type: string
        provider_type:
          description: Type of the secrets provider
          type: string
      type: object
    pkg_api_v1.createSecretResponse:
      description: Response after creating a secret
      properties:
        key:
          description: Secret key that was created
          type: string
        message:
          description: Success message
          type: string
      type: object
  securitySchemes:
    BearerAuth:
      description: 'OAuth 2.0 Bearer token authentication. Format: "Bearer {token}"'
      in: header
      name: Authorization
      type: apiKey
externalDocs:
  description: ''
  url: ''