Hyperbrowser Secrets API

openapi: 3.2.0
info:
  title: Hyperbrowser Secrets API
  version: 1.0.0
servers:
- url: https://api.hyperbrowser.ai
  description: Production server
tags:
- name: Secrets
paths:
  /api/secrets/public-key:
    get:
      summary: Get the secrets public key
      operationId: getSecretsPublicKey
      description: 'Returns the RSA public key that you encrypt secret values to before uploading them with POST /api/secrets/{id}/versions. Doesn''t require authentication. Don''t cache the key: after a key rotation, uploads encrypted to the old key return 409 SECRET_KEY_OUTDATED, and you fetch the key again.'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SecretsPublicKey'
        '503':
          description: 'SECRETS_NOT_CONFIGURED: secrets aren''t available on this deployment.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SecretErrorResponse'
      tags:
      - Secrets
  /api/secrets:
    get:
      summary: List secrets
      operationId: listSecrets
      description: Lists your team's secrets, sorted by name. Values are never returned. Secrets are enabled for teams on request; please contact support to enable them (otherwise 403 SECRETS_FEATURE_DISABLED). Restricted API keys need the secrets.read scope. When you're signed in rather than using an API key, you must be a team owner or admin (otherwise 403 SECRETS_ADMIN_REQUIRED).
      security:
      - ApiKeyAuth: []
      parameters:
      - name: page
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          default: 1
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 20
        description: Secrets per page.
      - name: search
        in: query
        required: false
        schema:
          type: string
          maxLength: 256
        description: Only secrets whose name contains this text, ignoring case.
      - name: type
        in: query
        required: false
        schema:
          $ref: '#/components/schemas/SecretType'
        description: Only secrets of this type.
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SecretListResponse'
        '400':
          description: Invalid query parameters.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SecretErrorResponse'
        '401':
          description: Authentication required.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SecretErrorResponse'
        '403':
          description: API_KEY_SCOPE_DENIED (the API key lacks a required scope), SECRETS_FEATURE_DISABLED, or SECRETS_ADMIN_REQUIRED.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SecretErrorResponse'
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SecretErrorResponse'
      tags:
      - Secrets
    post:
      summary: Create a secret
      operationId: createSecret
      description: Creates a secret without a value. Then upload its value with POST /api/secrets/{id}/versions, encrypted with the `encryptionContext` this returns. A team can have at most 100 secrets. Secrets are enabled for teams on request; please contact support to enable them (otherwise 403 SECRETS_FEATURE_DISABLED). Restricted API keys need the secrets.manage scope. When you're signed in rather than using an API key, you must be a team owner or admin (otherwise 403 SECRETS_ADMIN_REQUIRED).
      security:
      - ApiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateSecretParams'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Secret'
        '400':
          description: Invalid request body, or SECRET_METADATA_INVALID.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SecretErrorResponse'
        '401':
          description: Authentication required.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SecretErrorResponse'
        '403':
          description: API_KEY_SCOPE_DENIED (the API key lacks a required scope), SECRETS_FEATURE_DISABLED, or SECRETS_ADMIN_REQUIRED.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SecretErrorResponse'
        '409':
          description: 'SECRET_NAME_TAKEN: a secret with this name exists. SECRET_LIMIT_REACHED: your team has 100 secrets.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SecretErrorResponse'
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SecretErrorResponse'
      tags:
      - Secrets
  /api/secrets/{id}:
    get:
      summary: Get a secret
      operationId: getSecret
      description: Returns a secret and its stored versions. Values are never returned. Secrets are enabled for teams on request; please contact support to enable them (otherwise 403 SECRETS_FEATURE_DISABLED). Restricted API keys need the secrets.read scope. When you're signed in rather than using an API key, you must be a team owner or admin (otherwise 403 SECRETS_ADMIN_REQUIRED).
      security:
      - ApiKeyAuth: []
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
        description: Secret ID.
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SecretDetail'
        '400':
          description: Invalid secret ID.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SecretErrorResponse'
        '401':
          description: Authentication required.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SecretErrorResponse'
        '403':
          description: API_KEY_SCOPE_DENIED (the API key lacks a required scope), SECRETS_FEATURE_DISABLED, or SECRETS_ADMIN_REQUIRED.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SecretErrorResponse'
        '404':
          description: 'SECRET_NOT_FOUND: no secret with this ID in your team.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SecretErrorResponse'
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SecretErrorResponse'
      tags:
      - Secrets
    patch:
      summary: Update a secret
      operationId: updateSecret
      description: 'Updates a secret''s description or metadata, such as its allowed origins, without uploading a new value. Metadata is merged by top-level member: each member you send replaces the stored one, and `null` removes it. Secrets are enabled for teams on request; please contact support to enable them (otherwise 403 SECRETS_FEATURE_DISABLED). Restricted API keys need the secrets.manage scope. When you''re signed in rather than using an API key, you must be a team owner or admin (otherwise 403 SECRETS_ADMIN_REQUIRED).'
      security:
      - ApiKeyAuth: []
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
        description: Secret ID.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateSecretParams'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Secret'
        '400':
          description: Invalid request body, neither description nor metadata given, or SECRET_METADATA_INVALID.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SecretErrorResponse'
        '401':
          description: Authentication required.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SecretErrorResponse'
        '403':
          description: API_KEY_SCOPE_DENIED (the API key lacks a required scope), SECRETS_FEATURE_DISABLED, or SECRETS_ADMIN_REQUIRED.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SecretErrorResponse'
        '404':
          description: 'SECRET_NOT_FOUND: no secret with this ID in your team.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SecretErrorResponse'
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SecretErrorResponse'
      tags:
      - Secrets
    delete:
      summary: Delete a secret
      operationId: deleteSecret
      description: Permanently deletes a secret and all its versions. A secret that a vault uses as an entry can't be deleted. Secrets are enabled for teams on request; please contact support to enable them (otherwise 403 SECRETS_FEATURE_DISABLED). Restricted API keys need the secrets.manage scope. When you're signed in rather than using an API key, you must be a team owner or admin (otherwise 403 SECRETS_ADMIN_REQUIRED).
      security:
      - ApiKeyAuth: []
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
        description: Secret ID.
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SecretDeleteResponse'
        '400':
          description: Invalid secret ID.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SecretErrorResponse'
        '401':
          description: Authentication required.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SecretErrorResponse'
        '403':
          description: API_KEY_SCOPE_DENIED (the API key lacks a required scope), SECRETS_FEATURE_DISABLED, or SECRETS_ADMIN_REQUIRED.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SecretErrorResponse'
        '404':
          description: 'SECRET_NOT_FOUND: no secret with this ID in your team.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SecretErrorResponse'
        '409':
          description: 'SECRET_IN_USE: a vault uses this secret; change or delete the vault first.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SecretErrorResponse'
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SecretErrorResponse'
      tags:
      - Secrets
  /api/secrets/{id}/versions:
    post:
      summary: Add a secret version
      operationId: addSecretVersion
      description: Uploads a new value as the secret's next version. Encrypt the value on your side as a compact JWE (RSA-OAEP-256 and A256GCM) to the key from GET /api/secrets/public-key, with the protected header `{alg, enc, kid, ctx}`, where `ctx` is the secret's `encryptionContext`. The SDKs and CLI do this for you. A secret keeps at most 10 versions. Secrets are enabled for teams on request; please contact support to enable them (otherwise 403 SECRETS_FEATURE_DISABLED). Restricted API keys need the secrets.manage scope. When you're signed in rather than using an API key, you must be a team owner or admin (otherwise 403 SECRETS_ADMIN_REQUIRED).
      security:
      - ApiKeyAuth: []
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
        description: Secret ID.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AddSecretVersionParams'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SecretVersion'
        '400':
          description: 'Invalid request body, or SECRET_ENVELOPE_INVALID: the envelope isn''t a valid compact JWE for this secret (for example, a different `ctx`) or the value exceeds 32 KiB.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SecretErrorResponse'
        '401':
          description: Authentication required.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SecretErrorResponse'
        '403':
          description: API_KEY_SCOPE_DENIED (the API key lacks a required scope), SECRETS_FEATURE_DISABLED, or SECRETS_ADMIN_REQUIRED.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SecretErrorResponse'
        '404':
          description: 'SECRET_NOT_FOUND: no secret with this ID in your team.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SecretErrorResponse'
        '409':
          description: 'SECRET_KEY_OUTDATED: the envelope was encrypted to an old public key; fetch the current key and encrypt again. SECRET_LIMIT_REACHED: the secret has 10 versions; delete an old one first.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SecretErrorResponse'
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SecretErrorResponse'
        '503':
          description: 'SECRETS_NOT_CONFIGURED: secrets aren''t available on this deployment.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SecretErrorResponse'
      tags:
      - Secrets
  /api/secrets/{id}/versions/{version}:
    delete:
      summary: Delete a secret version
      operationId: deleteSecretVersion
      description: 'Permanently deletes an older version of a secret. You can''t delete the latest version: add a new version or delete the secret instead. Secrets are enabled for teams on request; please contact support to enable them (otherwise 403 SECRETS_FEATURE_DISABLED). Restricted API keys need the secrets.manage scope. When you''re signed in rather than using an API key, you must be a team owner or admin (otherwise 403 SECRETS_ADMIN_REQUIRED).'
      security:
      - ApiKeyAuth: []
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
        description: Secret ID.
      - name: version
        in: path
        required: true
        schema:
          type: integer
          minimum: 1
          maximum: 2147483647
        description: Version number.
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SecretVersionDeleteResponse'
        '400':
          description: Invalid secret ID or version.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SecretErrorResponse'
        '401':
          description: Authentication required.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SecretErrorResponse'
        '403':
          description: API_KEY_SCOPE_DENIED (the API key lacks a required scope), SECRETS_FEATURE_DISABLED, or SECRETS_ADMIN_REQUIRED.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SecretErrorResponse'
        '404':
          description: SECRET_NOT_FOUND or SECRET_VERSION_NOT_FOUND.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SecretErrorResponse'
        '409':
          description: 'SECRET_VERSION_IS_LATEST: the latest version can''t be deleted. SECRET_VERSION_IN_USE: a vault pins this version.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SecretErrorResponse'
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SecretErrorResponse'
      tags:
      - Secrets
components:
  schemas:
    SecretMetadata:
      type: object
      properties:
        browser:
          $ref: '#/components/schemas/SecretBrowserMetadata'
      additionalProperties: false
      description: Settings that aren't secret, returned by the API and editable without uploading a new value. A `secret` or `totp` secret can't be filled into browser pages until `browser.allowedOrigins` is set. An `op_token` secret accepts only `{}` (otherwise 400 SECRET_METADATA_INVALID).
    SecretBrowserMetadata:
      type: object
      properties:
        allowedOrigins:
          type: array
          minItems: 1
          maxItems: 20
          items:
            type: string
            maxLength: 512
          description: Origins a page or frame must be on before anything is typed, as `scheme://host[:port]` with no path, such as `https://github.com`. A leading `*.` matches any subdomain but not the domain itself, and must name at least two labels (`*.example.com`); you can't use a wildcard with an IP address. Origins must use https, except `http://localhost`, `http://127.0.0.1` and `http://[::1]`. Hyperbrowser lowercases origins, drops default ports and removes duplicates. An invalid entry returns 400 SECRET_METADATA_INVALID naming it.
      required:
      - allowedOrigins
      additionalProperties: false
      description: Where the secret may be typed into browser pages. Allowed for `secret` and `totp`.
    SecretsPublicKey:
      type: object
      properties:
        kid:
          type: string
          description: 'Key ID: the RFC 7638 SHA-256 thumbprint of the key. Put it in the `kid` header of your envelopes.'
        alg:
          type: string
          enum:
          - RSA-OAEP-256
        enc:
          type: string
          enum:
          - A256GCM
        jwk:
          type: object
          description: The RSA public key (at least 3072 bits) as a JWK.
          properties:
            kty:
              type: string
              enum:
              - RSA
            n:
              type: string
            e:
              type: string
            kid:
              type: string
            alg:
              type: string
              enum:
              - RSA-OAEP-256
            use:
              type: string
              enum:
              - enc
          required:
          - kty
          - n
          - e
          - kid
          - alg
          - use
      required:
      - kid
      - alg
      - enc
      - jwk
    CreateSecretParams:
      type: object
      properties:
        name:
          type: string
          pattern: ^[a-zA-Z0-9][a-zA-Z0-9_-]{0,127}$
          description: 1-128 letters, digits, `_` or `-`, starting with a letter or digit. Unique within your team.
        description:
          type: string
          maxLength: 1024
          default: ''
          description: Trimmed before it's stored.
        type:
          allOf:
          - $ref: '#/components/schemas/SecretType'
          default: secret
        metadata:
          allOf:
          - $ref: '#/components/schemas/SecretMetadata'
          description: For `secret` and `totp`, you can set `browser.allowedOrigins` now or later with PATCH /api/secrets/{id}. `op_token` accepts only `{}`.
      required:
      - name
      additionalProperties: false
    AddSecretVersionParams:
      type: object
      properties:
        envelope:
          type: string
          maxLength: 65536
          description: 'The value, encrypted on your side as a compact JWE: five canonical, unpadded base64url segments. Wrap the content key with RSA-OAEP-256 using the key from GET /api/secrets/public-key, and encrypt the content with A256GCM. The protected header must hold exactly `alg` (`RSA-OAEP-256`), `enc` (`A256GCM`), `kid` (the public key''s `kid`) and `ctx` (the secret''s `encryptionContext`, copied verbatim). The plaintext is the value as UTF-8: any string for `secret`; a base32 seed (spaces, hyphens and line breaks are ignored, `=` padding only at the end) or an `otpauth://totp/` URI (with `secret` and optionally `algorithm` SHA1, SHA256 or SHA512, `digits` 6 or 8, and `period` 1-300) for `totp`; a 1Password service account token for `op_token`. The value can be at most 32 KiB, without NUL bytes, and the envelope at most 64 KiB. The API checks the envelope''s structure but can''t decrypt it, so it can''t check the value: an invalid TOTP seed returns 422 SECRET_VALUE_INVALID when it''s used. The Hyperbrowser SDKs and CLI validate the value and build the envelope for you, so we recommend using them rather than encrypting by hand.'
      required:
      - envelope
      additionalProperties: false
    SecretListResponse:
      type: object
      properties:
        secrets:
          type: array
          items:
            $ref: '#/components/schemas/Secret'
        totalCount:
          type: integer
        page:
          type: integer
        perPage:
          type: integer
      required:
      - secrets
      - totalCount
      - page
      - perPage
    UpdateSecretParams:
      type: object
      description: Provide at least one of `description` and `metadata`.
      properties:
        description:
          type: string
          maxLength: 1024
          description: Replaces the description. Trimmed before it's stored.
        metadata:
          type: object
          properties:
            browser:
              type:
              - object
              - 'null'
              description: Replaces the secret's browser settings, or removes them with `null`, after which the secret can't be filled until origins are set again.
              properties:
                allowedOrigins:
                  type: array
                  minItems: 1
                  maxItems: 20
                  items:
                    type: string
                    maxLength: 512
                  description: Origins a page or frame must be on before anything is typed, as `scheme://host[:port]`. The same rules as `SecretBrowserMetadata.allowedOrigins` apply.
              required:
              - allowedOrigins
              additionalProperties: false
          additionalProperties: false
          description: 'Merged into the stored metadata by top-level member: each member you send replaces the stored one, `null` removes it, and members you don''t send are kept. So `{"browser": {"allowedOrigins": [...]}}` replaces the allowed origins, and `{"browser": null}` clears them. `op_token` secrets accept only `{}`.'
      minProperties: 1
      additionalProperties: false
    SecretDetail:
      allOf:
      - $ref: '#/components/schemas/Secret'
      - type: object
        properties:
          versions:
            type: array
            items:
              $ref: '#/components/schemas/SecretVersion'
            description: Stored versions, newest first. Values are never returned.
        required:
        - versions
    SecretDeleteResponse:
      type: object
      properties:
        deleted:
          type: boolean
          enum:
          - true
        id:
          type: string
          format: uuid
        name:
          type: string
      required:
      - deleted
      - id
      - name
    SecretType:
      type: string
      enum:
      - secret
      - totp
      - op_token
      description: 'What the value is. Fixed at creation. `secret`: any string, set as an environment variable and, once it has allowed origins, typed into browser pages. `totp`: an authenticator seed (base32, or an `otpauth://totp/` URI); environment variables get the code current when the process starts, and fills type the code current at fill time. `op_token`: a 1Password service account token, used only to read the `onePassword` fields of a sandbox create, process start or browser credential fill; it''s never an environment variable, a vault entry or a value typed into a page. Treat types you don''t recognize as opaque: more may be added.'
    SecretVersion:
      type: object
      properties:
        version:
          type: integer
          minimum: 1
        kid:
          type: string
          description: ID of the public key the envelope was encrypted to.
        createdAt:
          type: string
          format: date-time
      required:
      - version
      - kid
      - createdAt
    Secret:
      type: object
      description: A secret. The API never returns its value.
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
          pattern: ^[a-zA-Z0-9][a-zA-Z0-9_-]{0,127}$
          description: 1-128 letters, digits, `_` or `-`, starting with a letter or digit. Unique within your team.
        description:
          type: string
          maxLength: 1024
        type:
          $ref: '#/components/schemas/SecretType'
        metadata:
          $ref: '#/components/schemas/SecretMetadata'
        encryptionContext:
          type: string
          description: 'Copy this verbatim into the `ctx` header of every envelope you upload for this secret. Don''t build it yourself: it includes the secret''s type for types other than `secret`, and an envelope sealed with another context returns 400 SECRET_ENVELOPE_INVALID.'
        latestVersion:
          type:
          - integer
          - 'null'
          description: The newest version number, or null until a value is uploaded.
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
      required:
      - id
      - name
      - description
      - type
      - metadata
      - encryptionContext
      - latestVersion
      - createdAt
      - updatedAt
    SecretErrorResponse:
      type: object
      properties:
        code:
          type: string
          description: Machine-readable error code, such as SECRET_NOT_FOUND.
        message:
          type: string
        error:
          type: string
          description: Set instead of `code` by authentication and API key scope errors (API_KEY_SCOPE_DENIED).
        requiredScopes:
          type: array
          items:
            type: string
          description: The scope the API key is missing, with API_KEY_SCOPE_DENIED.
        retryable:
          type: boolean
          description: Whether repeating the same request can succeed. Set on delivery errors.
        details:
          type: object
          additionalProperties: true
          description: Extra information for some codes, such as `origin` for CREDENTIAL_ORIGIN_NOT_ALLOWED or `pages` for CREDENTIAL_PAGE_AMBIGUOUS.
      description: HTTP failure. Secret errors include `code` and `message`; request validation errors include only `message`; API key scope errors include `error`, `message` and `requiredScopes`.
    SecretVersionDeleteResponse:
      type: object
      properties:
        deleted:
          type: boolean
          enum:
          - true
        version:
          type: integer
      required:
      - deleted
      - version
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
    X402SessionManagement:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: The managementToken from the X402 session purchase response. Valid for 24 hours and scoped to that session; no API key or further payment is required.
x-provenance:
  method: harvested
  publisher: Hyperbrowser
  source: https://www.hyperbrowser.ai/docs/openapi.json
  note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
    stamped by stamp-openapi-provenance.py (roadmap#793)