ZELF
Zelf Documentation
Zelf Documentation
  • Welcome
  • Getting Started
    • How it works
    • WhitePaper
    • Zelf Proofs vs Others
    • Privacy Preserving
    • Use cases
    • Downloads
  • Functions
    • Authentication
    • Create a ZelfProof
    • Decrypt a ZelfProof
    • Preview ZelfProof
  • Zelf Name Service
    • Offline Version
      • Decryption
    • Online Version
      • Retrieve public key
      • Create a session
      • PGP Encryption
      • Lease a Zelf Name
      • Preview a ZelfName
      • Decrypt a ZelfName
    • Arweave ZNS Storage
    • Zelf Wallet Design
  • BlockChains
    • MINA
      • Get Balance
      • Get Token
      • Get Transactions
    • ETH
      • Adress Lookup
      • Transactions list
      • Transaction details
      • Gas Tracker
  • Integrations
  • Zelf Legal
    • Team Members
    • Terms of Use
    • Privacy Policy
  • Airdrop
    • Airdrop Rules
    • Reglas de Airdrop
    • Pricing per Domain
  • Verify our Partners
    • Acquisition Team
  • Roadmap
    • Q1 2025
    • Q2 2025
    • Q3 2025
    • Q4 2025
Powered by GitBook
On this page
  • Endpoint
  • Body
  • Responses

Was this helpful?

  1. Functions

Decrypt a ZelfProof

With this endpoint you can decrypt the content stored in the Zero Knowledge Face Proof provided by Zelf.

PreviousCreate a ZelfProofNextPreview ZelfProof

Last updated 4 months ago

Was this helpful?

Endpoint

https://api.zelf.world/api/zelf-proof/decrypt

This endpoint is used to verify the raw hash bytes against a face, thereby decrypting the associated metadata.

Request

  • Endpoint: /api/zelf-proof/decrypt

  • Method: POST

  • Content-Type: application/json

Body

The request body should be a JSON object containing the following fields:

{
  "faceBase64": "face_base_64_photo",
  "livenessLevel": "REGULAR",
  "os": "DESKTOP",
  "password": "(optional) password",
  "zelfProof": "<your_zelf_proof>",
  "verifierKey": "(optional) verifiers_auth_key"
}

Fields:

  • faceBase64: string (Required) - Base64 encoded face image data that will be compared against the ZelfProof.

  • livenessLevel: string (Optional) - Specifies the tolerance for face liveness checks. E.g., "REGULAR".

  • os: string (Optional) - The operating system from where the request originates, e.g., "DESKTOP".

  • password: string (Optional) - A password if required to decrypt the ZelfProof.

  • zelfProof: string (Required) - The ZelfProof in base64 format that needs to be verified and decrypted.

  • verifierKey: string (Optional) - An authentication key required for decrypting the ZelfProof if specified.

Responses

  • 200 OK: The request was successful, and the decrypted data from the ZelfProof is returned in JSON format.

    {
      "publicData": {
        "variable1": "string",
        "variable2": "string",
        "variable3": "string"
      },
      "difficulty": "EASY",
      "faceCropBase64": "string",
      "metadata": {
        "mnemonic": "string",
        "variable2": "string",
        "variable3": "string"
      },
      "identifier": "string"
    }
  • 400 Bad Request: There was an error with the request. Possible error codes include:

    {
      "code": "ERR_INVALID_IMAGE",
      "message": "Invalid base64 string for the face image."
    }
  • 401 Unauthorized: The API Key is not present in the X-api-key header.

    {
      "code": "ERR_API_KEY_NOT_PRESENT",
      "message": "API Key must be present in the x-api-key header."
    }
  • 403 Forbidden: The API Key is incorrect or there is an issue with licensing. Possible error codes include:

    • ERR_API_KEY_NOT_VALID: The provided API Key is not valid.

    • ERR_LICENSE_EXPIRED: The Zelf SDK license has expired.

    • ERR_CANNOT_CONNECT_TO_TIME_SERVER: Cannot connect to the time server to verify license expiry.

    • ERR_CANNOT_CONNECT_TO_HOME_SERVER: Cannot connect to the home server to verify license expiry.

    • ERR_NUMBER_OF_AVAILABLE_INSTANCES_EXCEEDED: The number of available instances for this license has been exceeded.

  • 413 Payload Too Large: The request sent is too large. Reduce the size of the image or data.

    {
      "code": "ERR_PAYLOAD_IS_TOO_LARGE",
      "message": "The request sent is too big. Please try reducing the size of image(s)/data."
    }
  • 422 Unprocessable Entity: The request is invalid due to a specific error related to its content.

    {
      "code": "ERR_UNPROCESSABLE_CONTENT",
      "message": "Invalid request: <specific message related to error>"
    }

Error Codes

Here are some specific error codes that might be returned during verification:

  • ERR_INVALID_IMAGE: Invalid base64 string for the face image.

  • ERR_NO_FACE_DETECTED: No face detected in the image.

  • ERR_MULTIPLE_FACES_DETECTED: Multiple faces detected in the image.

  • ERR_INVALID_ZELFPROOF_BYTES: The provided hash bytes could not be interpreted as a valid base64 string.

  • ERR_PARSE_FAILED: The hash could not be interpreted as a valid hash.

  • ERR_PASSWORD_REQUIRED: A password is required to decrypt the hash but was not provided.

  • ERR_INVALID_PASSWORD: The provided password is invalid.

  • ERR_LIVENESS_FAILED: The user's face image in face_base_64 is determined to not be live and require_live_face was set to true during hash creation.

  • ERR_VERIFICATION_FAILED: Decryption failed due to the face_base_64 not matching the face used to create the hash.

Additional Liveness Error Codes:

If the face_base_64 is determined to be not suitable for liveness, the following error codes may be returned:

  • ERR_LIVENESS_FACE_ANGLE_TOO_LARGE: The face angle is too large (the user is not facing the camera).

  • ERR_LIVENESS_FACE_IS_OCCLUDED: The face is occluded (e.g., by a mask).

  • ERR_LIVENESS_FACE_CLOSE_TO_BORDER: The face is too close to the border of the image.

  • ERR_LIVENESS_FACE_TOO_SMALL: The face is too small in the image.

  • ERR_LIVENESS_EYES_CLOSED: The eyes are closed in the image.