> ## Documentation Index > Fetch the complete documentation index at: https://hyperbrowser.ai/docs/llms.txt > Use this file to discover all available pages before exploring further. # Add a secret version > Upload a new encrypted value for a secret. See the [secrets guide](/docs/sandboxes/secrets) for SDK and CLI examples, and [credential fill](/docs/sessions/credentials) for website logins. ## OpenAPI ````yaml openapi.json POST /api/secrets/{id}/versions openapi: 3.0.1 info: title: Hyperbrowser API version: 1.0.0 servers: - url: https://api.hyperbrowser.ai description: Production server security: [] paths: /api/secrets/{id}/versions: post: summary: Add a secret version 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). operationId: addSecretVersion 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' security: - ApiKeyAuth: [] components: schemas: 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 and hyphens 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 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 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`. securitySchemes: ApiKeyAuth: type: apiKey in: header name: x-api-key ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.