Encrypt HumanID

Endpoint

POST https://api.verifik.co/v2/human-id/encrypt

Creates a HumanID (verifiable credential) by encrypting metadata of any kind and storing it in IPFS, a decentralized alternative to conventional cloud solutions (AWS, Azure, Google Cloud). Each HumanID can later be verified by the owner without storing the owner's biometric data.

HumanAuthn uses encryption from zelf.world. The Verifik product field is humanID.

Headers

Name	Value
Content-Type	application/json
Authorization	Bearer <token>

Params

Name	Type	Required	Description
publicData	object	Yes	Public data stored with the HumanID (string key-value pairs)
metadata	object	Yes	Private metadata encrypted into the HumanID (string key-value pairs)
faceBase64	string	Yes	Base64 encoded facial image
os	string	Yes	Operating system (DESKTOP, ANDROID, IOS)
identifier	string	Yes	Unique identifier (alphanumeric only, no spaces or special characters)
requireLiveness	boolean	Yes	Require a live face when decrypting later
livenessDetectionPriorCreation	boolean	No	Require a live face when creating the HumanID
tolerance	string	No	Liveness anti-spoof strictness (SOFT, REGULAR, HARDENED, REGULAR_HARD, REGULAR_SOFT). Defaults to HARDENED when requireLiveness is true
password	string	No	Optional password for additional security
referenceFaceBase64	string	No	Optional reference face image
verifierKey	string	No	Optional verifier key
storageProvider	string	No	Store in IPFS or return without Verifik persistence (ipfs, none). Defaults to ipfs
livenessLevel	string	No	Ignored. This proxy does not forward livenessLevel; use tolerance

Request

Node.js

const fetch = require("node-fetch");

async function run() {
  const res = await fetch("https://api.verifik.co/v2/human-id/encrypt", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      Authorization: `Bearer ${process.env.VERIFIK_TOKEN}`,
    },
    body: JSON.stringify({
      faceBase64: "<base64_image>",
      requireLiveness: false,
      tolerance: "HARDENED",
      password: "1234",
      os: "DESKTOP",
      identifier: "randomid",
      publicData: {
        "a": "1",
        "b": "2",
        "vida": "true"
      },
      metadata: {
        "secretA": "3",
        "secretB": "sijfoidjfijdifj"
      }
    }),
  });
  console.log(await res.json());
}

run();

PHP

<?php
$ch = curl_init("https://api.verifik.co/v2/human-id/encrypt");
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Content-Type: application/json",
    "Authorization: Bearer " . getenv("VERIFIK_TOKEN")
]);
$body = json_encode([
    "faceBase64" => "<base64_image>",
    "requireLiveness" => false,
    "tolerance" => "HARDENED",
    "password" => "1234",
    "os" => "DESKTOP",
    "identifier" => "randomid",
    "publicData" => [
        "a" => "1",
        "b" => "2",
        "vida" => "true"
    ],
    "metadata" => [
        "secretA" => "3",
        "secretB" => "4"
    ]
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, $body);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);
echo $response;

Python

import os, requests

url = "https://api.verifik.co/v2/human-id/encrypt"
headers = {
    "Content-Type": "application/json",
    "Authorization": f"Bearer {os.getenv('VERIFIK_TOKEN')}"
}
payload = {
    "faceBase64": "<base64_image>",
    "requireLiveness": False,
    "tolerance": "HARDENED",
    "password": "1234",
    "os": "DESKTOP",
    "identifier": "randomid",
    "publicData": {
        "a": "1",
        "b": "2",
        "vida": "true"
    },
    "metadata": {
        "secretA": "3",
        "secretB": "4"
    }
}
r = requests.post(url, json=payload, headers=headers)
print(r.json())

Go

package main

import (
    "bytes"
    "encoding/json"
    "fmt"
    "net/http"
    "os"
)

func main() {
    payload := map[string]interface{}{
        "faceBase64": "<base64_image>",
        "requireLiveness": false,
        "tolerance": "HARDENED",
        "password": "1234",
        "os": "DESKTOP",
        "identifier": "randomid",
        "publicData": map[string]string{
            "a": "1",
            "b": "2",
            "vida": "true",
        },
        "metadata": map[string]string{
            "secretA": "3",
            "secretB": "4",
        },
    }
    b, _ := json.Marshal(payload)
    req, _ := http.NewRequest("POST", "https://api.verifik.co/v2/human-id/encrypt", bytes.NewBuffer(b))
    req.Header.Set("Content-Type", "application/json")
    req.Header.Set("Authorization", "Bearer "+os.Getenv("VERIFIK_TOKEN"))
    resp, _ := http.DefaultClient.Do(req)
    defer resp.Body.Close()
    var out map[string]interface{}
    json.NewDecoder(resp.Body).Decode(&out)
    fmt.Println(out)
}

Response

200

{
  "data": {
    "humanID": "A39T6XGv2ld+/lwCeB11tcXKFUE2+4LkYwr2BfVwko8OvAqFCavD2S5o62IsxIH8QuQ6K9z1yJ6qhedWojVAhlMoufcpZLlhSknJTUMsql+FXXECoZ0elw3ZCKm1DHrrn3QoRtv3Pfc1EPB2fSoXan2RjFEnkolmrNA/FvRaEOgPeFLUlOFAVzYRVVsoFfe9N6pNZ9q5uCRti7vUwPz5LnObB5uVxFyNZFxZJKrJmqkEHWI+elEqQR/7KnGtwgyN4TNnVGdbyRUUZ8eTztGal5VHIDwYdKxIbjDb1x+xz/elCShcHr4K2QhG+cefp1hj6GFg8BSLF83Wk5U20Cm5V6G0F3Vjk4yNDc7IQB6OfvEDsD8OEov4xBG51D7pw6ukFrw/FrlHBbR+KV6We8t7pJ5/vzFll1tZKcki4PoOXcu/DzmhEVVb0DoVRcB53sbxpU0G5aT0hRH2rhs1jI0yitSzISqFOTNCb7wm3CQoA2ZGndx4+DLaoKjOb/9RFlRyk2FWpM1QGAPGMbJbDeW1JrZmBTsWQ6vTr6U+JdCZA2ZxEXIsugpzbkbMMnisW8m+ddoYJm2TJTvYI8XX6bLtC6T6dEM0oFPbJkjcYdW6bemsaMm0+evZUdREs7E435jDXEoJEP0LOufTluGYcstrTqcwKtSwM5OKK9qH27WNaWcybYrKw8tA0RBUf1jDc8ChHiKXRtiUQ3JxKzK2qLnlpBYLo/0Kyy0tYP7xK1lhxaJvMks8igH/jOuyjqLL0MmOs9EnCGZayJD/UQcu84XgDQKmVxk2zFUVhol7HlcRgpMisVaSawWhpnZtPFAeV+rpJgYAR8g4NjhZ7d9QGuHTdrxmGhHZcEyTqblMx4Kx4UVdWKzvHgaFjFFYag2w",
    "ipfs": {
      "url": "https://blush-selective-earwig-920.mypinata.cloud/ipfs/bafkreibu6ouy66tv7mmqbf4rxjd2tywdhfad2vri2sk562bltuz663imwu",
      "IpfsHash": "bafkreibu6ouy66tv7mmqbf4rxjd2tywdhfad2vri2sk562bltuz663imwu",
      "PinSize": 965,
      "Timestamp": "2025-10-15T15:22:00.333Z",
      "ID": "8e4dd38b-580d-4bf7-a71d-5c6d4e7dc008",
      "Name": "613375a1eab2fe08527f81e2_zk_randomid_93558.json",
      "NumberOfFiles": 1,
      "MimeType": "application/json",
      "GroupId": "861b93d7-9795-461d-b479-31f751d6869e",
      "pinned": true,
      "web3": true,
      "name": "613375a1eab2fe08527f81e2_zk_randomid_93558.json",
      "metadata": [
        "a",
        "b",
        "vida"
      ]
    }
  },
  "credits": {
    "amount": -0.84,
    "status": "approved",
    "category": "usage",
    "client": "613375a1eab2fe08527f81e2",
    "superAdmin": null,
    "expensesGroup": "613375a1eab2fe08527f81e2_zk_randomid_93558",
    "product": "humanAuthn",
    "transaction": null,
    "expiresAt": null,
    "isExpired": false,
    "referenceCredit": null,
    "_id": "68efbc187fb658e0366a3019",
    "updatedAt": "2025-10-15T15:22:00.907Z",
    "createdAt": "2025-10-15T15:22:00.907Z",
    "__v": 0
  }
}

401

{
  "message": "Authentication required",
  "code": "UNAUTHORIZED"
}

403

{
  "message": "Access Forbidden",
  "code": "FORBIDDEN"
}

409

{
  "message": "\"faceBase64\" is required",
  "code": "MissingParameter"
}

500

{
  "message": "internal_error",
  "code": "ERROR"
}

Notes

• The humanID token contains encrypted HumanData, raw metadata only accessible to the owner of the HumanID.
• IPFS data includes metadata about the stored HumanID and public data keys
• Credits are deducted for HumanID creation (typically 0.84 credits)
• The identifier must be alphanumeric only (no spaces or special characters)
• publicData and metadata must contain only string key-value pairs
• Liveness detection can be enabled for biometric security
• Password protection adds an extra layer and is an option that can be included in the security of the HumanID