Skip to main content
POST
Encrypt a payload

Authorizations

X-Qanapi-Authorization
string
header
required

A machine credential, qk_ followed by its secret. Only a hash of the secret is stored, so a key is displayed exactly once, when it is created or rotated. A key reaches only the configurations it is linked to.

It may also be sent as Authorization: Bearer qk_..., which is recognised by the prefix.

Headers

X-Qanapi-Fields
string

Comma-separated dot paths to encrypt or decrypt, for example ssn,user.address.postcode. Absent in whole-body mode. A path that matches nothing is skipped unless X-Qanapi-Require-Fields is set.

A numeric segment indexes one element of an array, so items.0.card reaches exactly that element. A segment that is not a number, applied to an array, is mapped over every element instead: items.card reaches the card of each object in items, and each one counts separately towards X-Qanapi-Action-Count.

Naming an array itself encrypts it whole, as one value, rather than element by element.

Example:

"ssn,user.dob,items.card"

X-Qanapi-Full-Body
string

Treat the whole body as one payload. Any of true, 1, yes or on turns it on; anything else, or the header's absence, leaves field mode in effect.

Example:

"true"

X-Qanapi-Mode
enum<string>

Alternative spelling of whole-body mode. Either spelling of the value selects it; any other value leaves field mode in effect.

Available options:
full_body,
full-body
X-Qanapi-Classification
string

Apply a classification to what is being encrypted, by slug or id. Refused unless the caller holds that clearance. Decryption reads the classification from the record, so this header has no effect there.

Example:

"top-secret"

X-Qanapi-Require-Fields
string

Fail the request when a named field path matched nothing, rather than returning the document unchanged. Off by default, and turned on by any of true, 1, yes or on.

Worth setting in any caller that would rather hear about a typo than store plaintext: without it, a mistyped path returns the original body with a success status, and only X-Qanapi-Action-Count: 0 tells the two apart. Nothing is changed when the request fails this way.

Example:

"true"

X-Qanapi-Destination
string<uri>

Forward the processed payload to this absolute URL and relay the answer back, with its own status, body and headers. Must be http or https. Every request header travels except x-qanapi-*, authorization and the hop-by-hop set. Restricted by an allowlist where the installation sets one.

Example:

"https://payments.internal/charge"

Path Parameters

proxy
string
required

The configuration's proxy slug. Sixteen random lowercase letters and digits unless one was pinned at creation.

Example:

"952zpx6vyig3sdyp"

Body

Any JSON document in field mode. In whole-body mode the body may be any bytes at all, including non-JSON.

Response

In field mode, the document with the named fields replaced by envelopes. In whole-body mode, one envelope as text/plain.

When X-Qanapi-Destination was set this is instead whatever the destination answered, relayed with its own status, body and headers, and stamped with X-Qanapi-Forwarded-To.

The response is of type object.