Sign in

v32

latestOpenAPI 3.1.0raw.githubusercontent.com2026-05-224341,4072.0 MB
Secrets

Create External

CreateExternal creates a secret vault for external email recipients.

post/api/v1/secrets/external

Request body

allowedEmailsstring[] nullable

External email addresses allowed to view this secret (1 to 64). Recipients authenticate via email magic link or Google OAuth.

contentTypestring

For FILE secrets: MIME content type of the original file. Ignored for TEXT secrets.

displayNamestring

Optional cleartext label visible to the creator in "My Secrets" view. Not encrypted — do not put sensitive data here.

expiresInstring duration
fileSizestring int64

For FILE secrets: expected file size in bytes (max 1GB). Ignored for TEXT secrets.

filenamestring

For FILE secrets: original filename (sanitized server-side). Ignored for TEXT secrets.

inputFormat'SECRET_INPUT_FORMAT_UNSPECIFIED' | 'SECRET_INPUT_FORMAT_PLAINTEXT' | 'SECRET_INPUT_FORMAT_JSON' | 'SECRET_INPUT_FORMAT_YAML' | 'SECRET_INPUT_FORMAT_KEY_VALUE'

For TEXT secrets: hint about the plaintext format (e.g., JSON, YAML, key-value). Used by the viewer UI for syntax highlighting. Does not affect encryption.

maxViewsinteger

Maximum number of views before the secret is burned (0 = unlimited).

secretType'SECRET_TYPE_UNSPECIFIED' | 'SECRET_TYPE_TEXT' | 'SECRET_TYPE_FILE'

Secret type: TEXT or FILE. TEXT secrets use SetTextContent to upload encrypted content (max 64KB). FILE secrets use the upload_url from CreateResponse to upload encrypted content (max 1GB).

Response

Successful response

ageRecipientstring

Age X25519 recipient public key (format: "age1...") for client-side encryption. All content MUST be encrypted to this recipient using the Age encryption format before calling SetTextContent or uploading to upload_url. See: https://age-encryption.org

uploadUrlstring

For FILE secrets: capability URL for uploading the Age-encrypted file. Send an HTTP PUT request with the Age-encrypted file bytes as the body and Content-Type: application/octet-stream. The payload MUST begin with the Age header "age-encryption.org/v1\n". Maximum file size: 1GB. Empty for TEXT secrets.

vaultIdstring

Vault ID - primary identifier for this secret.