Create a ZelfProof

Encrypt Metadata

POST https://api.zelf.world/api/zelf-proof/encrypt

This endpoint allows the creation of a new ZelfProof as raw bytes encoded in base64. These are the same bytes used to generate the ZelfQR code.

Request

• Endpoint: /api/zelf-proof/encrypt

• Method: POST

• Content-Type: application/json

Request Body

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

{
  "livenessDetectionPriorCreation": false,
  "publicData": {
    "ethAddress": "0x13901AE0F17E2875E86C86721f9943598601b0C4"
  },
  "faceBase64": "face_image_bytes_as_base64",
  "livenessLevel": "REGULAR",
  "metadata": {
    "mnemonic": "pistol cloth equal legend category dry wine enjoy rookie artwork portion december"
  },
  "os": "DESKTOP",
  "password": "optional",
  "identifier": "A0123453",
  "referenceFaceBase64": "optional_base64_encoded_reference_face_image",
  "requireLiveness": true,
  "tolerance": "REGULAR",
  "verifierKey": "optional_auth_key"
}

Fields:

• livenessDetectionPriorCreation: Boolean (Optional) - If true, the face must be live to create the ZelfProof.

• publicData: object (Optional) - Cleartext data associated with the record, such as masked_id.

• faceBase64: string (Required) - Base64 encoded face image data.

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

• metadata: object (Optional) - Additional metadata in JSON format associated with the ZelfProof.

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

• password: string (Optional) - A password for additional security.

• identifier: string (Optional) - An ID associated with the record.

• referenceFaceBase64: string (Optional) - Base64 encoded reference face image. Used for matching with the faceBase64.

• requireLiveness: Boolean (Optional) - If true, the face must be live.

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

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

Responses

• 200 OK: The request was successful, and the hash bytes are returned in base64 format.

  {
    "zelfProof": "wV4DP6X2TUzD3QISAQdAhqpw8Wau9G1td1yoKeBdkBabX143gBojODIePPsQ
  5SEwmmCVDJaxDQe8tcxQUww/XicXEZS042TraT213VJ/w1KU17ZP40/x+vKr
  ySwxJJ1n0sMGAbaU75TzCo....JRBhMZpO0G+5IWrS+UXP0SqXc
  GvPOPkE53sh671wN1ritaM8Dnrs"
  }

• 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 Un processable 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:

• 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_REF_FACE_NOT_MATCHED: Reference face does not match the input face.

• ERR_LIVENESS_FAILED: Liveness check failed for the input face.

• ERR_LIVENESS_FACE_ANGLE_TOO_LARGE: The face angle is too large, making liveness check impossible.

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

Frequently Asked Questions (FAQs)

Q: What happens if someone else tries to generate a ZelfProof using my face?

A: ZelfEncrypt ensures that each ZelfProof is unique and tied to the specific conditions (metadata, password) provided at the time of creation. Without the exact same inputs, a different ZelfProof will be generated, preventing unauthorized access. That without considering that we require a liveness detection on the encryption as one of the params of our SDK/API function.

Q: Can the ZelfProof be used across different wallets/platforms?

A: Yes, a ZelfProof can be used across various platforms for authentication, encryption, and verification purposes. The integration is seamless and designed to work in diverse environments.

---

This documentation should serve as a comprehensive guide for understanding and implementing Zelf. If you need more specific sections or have additional details to include, feel free to contact us at [e-mail]