Skip to main content
Every header below is optional unless it is marked required. Anything not listed here is passed through untouched.

​
Authentication

Send one of these two. A request carrying both is authenticated as the API key, because a key names a narrower credential than the user that owns it.
​
string
An API key. Keys issued by this service are prefixed qk_.
​
string
A bearer token from POST /api/v3/auth/login, sent as Bearer <token>. An API key is also accepted here, as Bearer qk_..., and is recognised by its prefix.
Keys issued by this service use the qk_ prefix, not the qapi_ used by Qanapi Cloud. Update any secret scanning rule or client-side validation that matches on the cloud prefix, or it will fail to recognize a standalone key.
You can create, rotate and revoke keys in the API Keys section.

​
Content Control

​
string
Required, and application/json, on the management endpoints: users, API keys, configurations, classifications, policies, KMS and audit export. A JSON body sent without it is rejected there.The two encryption endpoints do not require it. They read the body directly, so field mode accepts JSON under any content type and whole-body mode accepts any bytes at all.Use application/jose when the body is an encrypted JWE. See Transport Encryption.
​
string
A comma-separated list of fields in the JSON payload to encrypt or decrypt. Everything not named is returned untouched.
Not required. Omitting it on an encryption call encrypts nothing, unless you selected whole-body mode with X-Qanapi-Full-Body.
Dot notation: target nested fields by path, for example user.address.zip.Arrays: a numeric segment indexes one element, so items.0.card reaches exactly that one. A segment that is not a number is mapped over every element instead, so items.card reaches the card of every object in items. Naming an array itself encrypts it whole, as a single value.A path that matches nothing in the payload is skipped rather than reported, unless you send X-Qanapi-Require-Fields.
​
string
Treat the whole body as one payload rather than selecting fields from it. Any of true, 1, yes or on turns it on.Encrypting this way returns a single envelope as text/plain, whatever the body was. Decrypting returns the original bytes under a content type inferred from them.
​
string
An alternative spelling of whole-body mode. Send full_body or full-body; any other value leaves field mode in effect.
​
string
Fail the request when a named field path matched nothing, rather than returning the body unchanged. Any of true, 1, yes or on turns it on, and nothing is changed when a request fails this way.
Without X-Qanapi-Require-Fields, a mistyped path is indistinguishable from a successful call: the response is your own plaintext, returned with a success status. Set this header in any client that would rather hear about a typo than store plaintext believing it is ciphertext.

​
Dot Notation Example

Request

​
Classifications

​
string
The id or slug of a classification to attach to the data being encrypted.
Any key generated for that request is tagged with the classification, so every later decryption of that data requires the caller to hold clearance for it. A caller without clearance cannot read it back.
This header applies to encryption only. Decryption reads the classification from the record itself, so sending it on a decrypt call has no effect. Applying a classification you do not hold yourself is refused, because it would let you write data you immediately could not read.

​
Advanced Routing

​
string
An absolute http or https URL to forward the processed payload to. The destination’s answer is relayed back to you with its own status, body and headers.
Your credentials are never forwarded. Every header beginning x-qanapi- is stripped, and so is Authorization, along with the hop-by-hop headers. No destination receives the credential you used with us, so a destination that needs its own must be given it another way.
Where the installation configures an allowlist of destination hosts, a URL outside it is refused.

​
Transport Encryption

For payloads that must stay unreadable even to the boundary terminating TLS in front of the service.
​
string
Set to application/jose to send the body as an RFC 7516 JWE, wrapped to the key from GET /api/v3/qanapi-public-key. application/jwt and application/jose+json are accepted as well, and a body that is plainly a compact JWE is recognised even without one of them.
​
string
The key_id of an RSA key in your KMS. The response is wrapped to it as a compact JWE and returned as application/jose, so only the holder of that key’s private half can read it. The spelling wrap_with_key_id is accepted as well.
Both work on any /api/v3 endpoint, not only the encryption ones. Where the installation requires it, a wrapped request must carry iat, exp and jti claims, which also make each payload single-use.

​
Tracing

​
string
Your own correlation id, preserved on the audit record and echoed on the response. It must be at most 64 characters of letters, digits, -, _, . or :; anything else is replaced with a generated id. Omit it and one is generated for you.

​
Response Headers

​
integer
How many cryptographic operations the request performed. A zero in field mode means no named path matched anything.
​
string
Present only when the answer was relayed from an X-Qanapi-Destination, naming it, so you can tell a proxied response from one this service produced.
​
integer
Requests allowed per minute, per node.
​
integer
Requests left in the current window.
​
integer
On an audit export, how many records the export contains.
​
string
On an audit export, whether the hash chain over the exported records verified. A false here is a compliance event in its own right, and the export is still returned so it can be examined.

Try it out

See these headers in action by testing the Encryption endpoints.