Preview ZelfProof

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

This endpoint allows you to retrieve information about a ZelfProof without decrypting the metadata with a face and perform the liveness test. This can be useful for obtaining basic details about the ZelfProof when decryption is not necessary or possible.

Request

• Endpoint: /api/zelf-proof/preview

• Method: POST

• Content-Type: application/json

Request Body

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

{
  "zelfProof": "<your_zelf_proof>",
  "verifierKey": "(optional) key_here"
}

Fields:

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

• verifierKey: string (Optional) - An authentication key required if specified for the ZelfProof. This key may be necessary for obtaining certain information from the ZelfProof.

Responses

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

  {
    "publicData": {
      "variable1": "string",
      "variable2": "string",
      "variable3": "string"
    },
    "requireLiveness": true,
    "passwordLayer": "NoPassword"
  }

• 400 Bad Request: There was an error with the request. Possible error codes include:

  {
    "code": "ERR_INVALID_HASH_BYTES",
    "message": "The provided hash is not a valid base64 string."
  }

  • ERR_INVALID_HASH_BYTES: The hash provided is not a valid base64 string.

  • ERR_PARSE_FAILED: The hash could not be parsed as a valid hash, or the verifierKey provided is incorrect.

• 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 during the parsing process:

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

• ERR_PARSE_FAILED: The hash could not be parsed as a valid hash, possibly due to an incorrect verifierKey.

• ERR_API_KEY_NOT_PRESENT: The required API Key is not present in the X-api-key header.

• ERR_API_KEY_NOT_VALID: The provided API Key is invalid.

• ERR_LICENSE_EXPIRED: The license for the Zelf SDK has expired and needs to be renewed.

• ERR_CANNOT_CONNECT_TO_TIME_SERVER: The Zelf SDK cannot connect to the time server to verify license expiry.

• ERR_CANNOT_CONNECT_TO_HOME_SERVER: The Zelf SDK 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.

• ERR_PAYLOAD_IS_TOO_LARGE: The request payload is too large and needs to be reduced in size.

• ERR_UNPROCESSABLE_CONTENT: The request content is invalid, possibly due to a specific error in the request body.