Decrypt a payload

curl --request POST \
  --url https://{host}/api/v3/encryption/{proxy}/decrypt \
  --header 'Content-Type: application/json' \
  --header 'X-Qanapi-Authorization: <api-key>' \
  --data '
{
  "name": "Jane Doe",
  "ssn": "QANAPI-RS:v1:MDFhMDg2ZGQ:Vpp6gZK4ZRUwgvpcnA:$"
}
'

import requests

url = "https://{host}/api/v3/encryption/{proxy}/decrypt"

payload = {
    "name": "Jane Doe",
    "ssn": "QANAPI-RS:v1:MDFhMDg2ZGQ:Vpp6gZK4ZRUwgvpcnA:$"
}
headers = {
    "X-Qanapi-Authorization": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-Qanapi-Authorization': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({name: 'Jane Doe', ssn: 'QANAPI-RS:v1:MDFhMDg2ZGQ:Vpp6gZK4ZRUwgvpcnA:$'})
};

fetch('https://{host}/api/v3/encryption/{proxy}/decrypt', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://{host}/api/v3/encryption/{proxy}/decrypt",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'name' => 'Jane Doe',
    'ssn' => 'QANAPI-RS:v1:MDFhMDg2ZGQ:Vpp6gZK4ZRUwgvpcnA:$'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-Qanapi-Authorization: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://{host}/api/v3/encryption/{proxy}/decrypt"

	payload := strings.NewReader("{\n  \"name\": \"Jane Doe\",\n  \"ssn\": \"QANAPI-RS:v1:MDFhMDg2ZGQ:Vpp6gZK4ZRUwgvpcnA:$\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-Qanapi-Authorization", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://{host}/api/v3/encryption/{proxy}/decrypt")
  .header("X-Qanapi-Authorization", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"name\": \"Jane Doe\",\n  \"ssn\": \"QANAPI-RS:v1:MDFhMDg2ZGQ:Vpp6gZK4ZRUwgvpcnA:$\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://{host}/api/v3/encryption/{proxy}/decrypt")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-Qanapi-Authorization"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"name\": \"Jane Doe\",\n  \"ssn\": \"QANAPI-RS:v1:MDFhMDg2ZGQ:Vpp6gZK4ZRUwgvpcnA:$\"\n}"

response = http.request(request)
puts response.read_body

{
  "name": "Jane Doe",
  "ssn": "123-45-6789"
}

{
  "message": "Unauthorized.",
  "error": "InvalidApiKeyException"
}

{
  "message": "Unauthorized.",
  "error": "InvalidApiKeyException"
}

{
  "message": "Unauthorized.",
  "error": "InvalidApiKeyException"
}

{
  "message": "API key not found",
  "error": "ApiKeyNotFoundException"
}

{
  "message": "Payload too large.",
  "error": "PayloadTooLarge"
}

{
  "message": "Unauthorized.",
  "error": "InvalidApiKeyException",
  "errors": {
    "type": [
      "The type field is required."
    ],
    "configuration_ids": [
      "No configuration has the id `...`."
    ]
  }
}

{
  "message": "Too many requests.",
  "error": "TooManyRequests"
}

{
  "message": "Unauthorized.",
  "error": "InvalidApiKeyException"
}

Encryption

Decrypt a payload

Requires the decrypt action on this configuration. The inverse of encrypt, with the same two modes and the same forwarding behaviour. Reading data already protected is always served, whatever the license says.

An envelope is refused unless it was produced in the configuration it is presented to, independently of the authentication tag, and unless the caller holds the clearance the record carries. Envelopes in the earlier qanapi: format are refused as a format error rather than attempted and failed.

X-Qanapi-Classification has no effect here: a record’s classification is read from the record.

POST

api

encryption

{proxy}

decrypt

Decrypt a payload

curl --request POST \
  --url https://{host}/api/v3/encryption/{proxy}/decrypt \
  --header 'Content-Type: application/json' \
  --header 'X-Qanapi-Authorization: <api-key>' \
  --data '
{
  "name": "Jane Doe",
  "ssn": "QANAPI-RS:v1:MDFhMDg2ZGQ:Vpp6gZK4ZRUwgvpcnA:$"
}
'

import requests

url = "https://{host}/api/v3/encryption/{proxy}/decrypt"

payload = {
    "name": "Jane Doe",
    "ssn": "QANAPI-RS:v1:MDFhMDg2ZGQ:Vpp6gZK4ZRUwgvpcnA:$"
}
headers = {
    "X-Qanapi-Authorization": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-Qanapi-Authorization': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({name: 'Jane Doe', ssn: 'QANAPI-RS:v1:MDFhMDg2ZGQ:Vpp6gZK4ZRUwgvpcnA:$'})
};

fetch('https://{host}/api/v3/encryption/{proxy}/decrypt', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://{host}/api/v3/encryption/{proxy}/decrypt",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'name' => 'Jane Doe',
    'ssn' => 'QANAPI-RS:v1:MDFhMDg2ZGQ:Vpp6gZK4ZRUwgvpcnA:$'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-Qanapi-Authorization: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://{host}/api/v3/encryption/{proxy}/decrypt"

	payload := strings.NewReader("{\n  \"name\": \"Jane Doe\",\n  \"ssn\": \"QANAPI-RS:v1:MDFhMDg2ZGQ:Vpp6gZK4ZRUwgvpcnA:$\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-Qanapi-Authorization", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://{host}/api/v3/encryption/{proxy}/decrypt")
  .header("X-Qanapi-Authorization", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"name\": \"Jane Doe\",\n  \"ssn\": \"QANAPI-RS:v1:MDFhMDg2ZGQ:Vpp6gZK4ZRUwgvpcnA:$\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://{host}/api/v3/encryption/{proxy}/decrypt")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-Qanapi-Authorization"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"name\": \"Jane Doe\",\n  \"ssn\": \"QANAPI-RS:v1:MDFhMDg2ZGQ:Vpp6gZK4ZRUwgvpcnA:$\"\n}"

response = http.request(request)
puts response.read_body

{
  "name": "Jane Doe",
  "ssn": "123-45-6789"
}

{
  "message": "Unauthorized.",
  "error": "InvalidApiKeyException"
}

{
  "message": "Unauthorized.",
  "error": "InvalidApiKeyException"
}

{
  "message": "Unauthorized.",
  "error": "InvalidApiKeyException"
}

{
  "message": "API key not found",
  "error": "ApiKeyNotFoundException"
}

{
  "message": "Payload too large.",
  "error": "PayloadTooLarge"
}

{
  "message": "Unauthorized.",
  "error": "InvalidApiKeyException",
  "errors": {
    "type": [
      "The type field is required."
    ],
    "configuration_ids": [
      "No configuration has the id `...`."
    ]
  }
}

{
  "message": "Too many requests.",
  "error": "TooManyRequests"
}

{
  "message": "Unauthorized.",
  "error": "InvalidApiKeyException"
}

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. A path that matches nothing is skipped unless X-Qanapi-Require-Fields is set.

Required unless whole-body mode is selected with X-Qanapi-Full-Body or X-Qanapi-Mode. A call that names no fields and asks for no whole-body mode would encrypt nothing, so it answers 422 rather than returning the document untouched under a success code.

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-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

The body is of type object.

Response

The plaintext, in the shape it was encrypted from. In field mode the document is returned as JSON.

In whole-body mode the original bytes are returned exactly as they were before encryption, but the envelope does not record the content type they were sent under, so one is inferred from the bytes themselves, in this order:

application/json when the body is valid UTF-8, begins with { or [, and parses as JSON.
application/xml when the body is valid UTF-8 and begins with <?xml or <.
application/octet-stream when the body is not valid UTF-8, which is the case for every binary payload.
text/plain; charset=utf-8 otherwise.

The inference is a best effort over content, not a record of what was sent. A caller that needs the original content type preserved must carry it alongside the envelope.

The response is of type object.

Details

Encryption

Classifications

Policies

Authentication

Users

Configurations

API Keys

Health

KMS

Audit

Transport

Decrypt a payload

Authorizations

Headers

Path Parameters

Body

Response