Encrypt a payload
Requires the encrypt action on this configuration, and a current
license: protecting new data is the one operation a lapsed license
refuses.
Two modes, chosen by header:
- Field mode, the default.
X-Qanapi-Fieldsnames dot-separated paths inside a JSON body. Each named leaf is replaced by an envelope string; everything else is returned untouched. A path that matches nothing is skipped, unlessX-Qanapi-Require-Fieldsis set. - Whole-body mode, selected by
X-Qanapi-Full-BodyorX-Qanapi-Mode. The whole body is treated as one payload and a single envelope is returned astext/plain, whatever the body was.
Every payload is AES-256-GCM under a fresh key encryption key and data encryption key, so a nonce is never reused under a key.
Setting X-Qanapi-Destination turns the call into a proxy: the
processed payload is sent on to that URL and the answer is relayed back.
Authorizations
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
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.
"ssn,user.dob,items.card"
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.
"true"
Alternative spelling of whole-body mode. Either spelling of the value selects it; any other value leaves field mode in effect.
full_body, full-body 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.
"top-secret"
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.
"true"
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.
"https://payments.internal/charge"
Path Parameters
The configuration's proxy slug. Sixteen random lowercase letters and digits unless one was pinned at creation.
"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.