Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
This guide complements your understanding of our API endpoints by delving into key generation, signing, and encryption. These steps are crucial for securing your data tokens when using zkPass.
This pair consists of two keys: a public key and a private key. Think of them like a lock and key combination.
Public Key: This key is freely shared and used to verify the authenticity of your signed data tokens.
Private Key: Keep this key safe! It's used for signing and decrypting your data tokens.
Signing your data tokens adds a digital signature using your private key. This signature acts like a tamper-proof seal, ensuring anyone receiving the token can confirm it hasn't been altered.
Encryption takes your data tokens and scrambles them using your private key. This makes the data unreadable by anyone who doesn't possess the corresponding public key (which you wouldn't share).
Before you get started with the zkPass API, here's what you'll need:
User Data Token
DVR Token
The zkPass API uses a familiar approach called basic authentication to ensure secure access. Here's what you'll need:
API Key: This unique identifier acts like your username for the API.
API Secret Key: Consider this your password, but much more secure. Keep it confidential!
To access the API, you'll need to provide both your API Key and API Secret Key in every request you make. They should be included in the authorization header of your requests.
No worries! If you haven't received your API credentials, simply fill out our easy-to-use form to request them. We'll get you set up in no time.
Our utilities section provides a detailed guide on creating a key pair. This key pair is used for signing and encrypting your user data token (and DVR token, if needed). Here's a quick overview of the steps involved:
This section explains how to use the zkPass service using any programming language that we don't currently support.
Make sure you have :
userDataToken
dvrToken
Read section for detail info.
zkPass enhances the security of your data during transport by encrypting it before sending it over the network. The are only two entities that can access the data: the holder and zkPass host running in a Trusted Execution Environment (TEE).
First, find the zkPass public key in the .well-known/jwks.json
file at this endpoint: The key you're looking for has a kid (Key ID) of "ServiceEncryptionPubK".
After this section you should have :
Encrypted User Data Token (in JWE Format).
Encrypted DVR Token (in JWE Format).
Here's the example
We are using elliptic curve cryptography (ECC) for our encryption. The key pair should be generated using P-256
curve. Ensure the generated key pair is in PEM
format.
The public key should be encoded in SPKI
format, and the private key should be encoded in PKCS#8
format.
PEM
format
SPKI
encoding
PEM
format
PKCS#8
encoding
Here's the example of generating key pair in Typescript.
After this section you should have a key pair consisting of :
publicKeyJWKS
privateKey
Ideally, the issuer & verifier should have different key pairs.
Make sure you have both them before proceeding to the next section.
Here's the example for publicKeyJWKS
and privateKey
.
This section provides a detailed reference for all zkPass API endpoints
Make sure you have key pair consisting of :
publicKeyJWKS
privateKey
Read Generate Key Pair section for detail info.
We need to sign User Data and Data Verification Request (DVR) before sending a request to the zkPass service. This ensures that the payload is not tampered during transport.
The JSON Web Key Set (JWKS) is a set of keys containing the public keys used to verify any JSON Web Token (JWT) issued by the Authorization Server and signed, You can find a complete definition of JWKS here.
Upload your publicKeyJWKS
so that it's accessible from the internet. This will be used by zkPass service to verify the validity of the user data.
Example of the uploaded publicKeyJWKS
A JSON Web Signature (abbreviated JWS) is an IETF-proposed standard (RFC 7515) for signing arbitrary data. This is used as the basis for a variety of web-based technologies including JSON Web Token. You can find a complete definition of JWS here.
This is an example code of how you can sign a JSON object as JWS format in Typescript. Let's say you uploaded your publicKeyJWKS
to https://mywebsite/my-keys.json
Example for User Data
Below is the example of Query in DVR, this query will be included in full DVR
Below is the example of full DVR that will be generated into DVR Token
After this section you should have :
User Data Token : User Data in JSON Web Signature (JWS) format.
DVR Token : DVR in JSON Web Signature (JWS) format.
Here's the example of User Data Token & DVR Token in JWS format.
Before using the Generating Proof Endpoint, There are three essential items you'll need to use the endpoint:
encryptedUserDataToken
: This token contains your encrypted user data
encryptedDvrToken
: This token holds your encrypted DVR data
apiToken
: This unique identifier authenticates your requests with the zkPass API
apiToken
is the base64 form of YOUR_API_KEY:YOUR_API_SECRET
.
For instructions on creating the encryptedUserDataToken
and encryptedDvrToken
, refer to our Utilities section. It provides a step-by-step guide that covers:
Generating a Key Pair: This creates the keys you'll use for signing your data.
Signing User Data and DVR: This step adds a digital signature to your data tokens, ensuring their authenticity.
Encrypting User Data and DVR: This encrypts your data tokens, making them unreadable by anyone without the decryption key.
Type | Value |
---|---|
Parameter | Description |
---|---|
Parameter | Type | Mandatory | Description |
---|---|---|---|
HTTP Method
POST
API endpoint (Playground)
https://playground-zkpass.ssi.id/v1/proof
Authorization
base64 form of YOUR_API_KEY:YOUR_API_SECRET
Content-Type
Indicates that the content being sent or received is JSON data
X-zkPass-Client
(Optional)
Optional Header, zkPass WS checks the zkPass client version if provided. The current supported version is 1.0.0
user_data_token
string
Mandatory
encrypted user data token in JWE format
dvr_token
string
Mandatory
encrypted dvr token in JWE format
400
E2001-EDeserializeError
Failed to deserialize the data
Our system failed to deserialize your data
400
E2002-ESerializeError
Failed to serialize the data
Our system failed to serialize data
400
E2008-ECustomError
Custom Error
Custom error
400
E2010-EEmptyParameter
Empty parameter was given
Our system detect there is no parameters given
400
NO_PARAMS
There is no dvr_token
& user_data_token
params
Missing dvr_token
and user_data_token
as request parameters
401
UNAUTHORIZED
Unauthorized, please input the correct token
Check your authorization token
403
FORBIDDEN
Please check your zkPass client version. Server version: current_version
Request in different version with current zkPass service version
404
NOT_FOUND
Api / Web you are searching is not found
Api / Web you are searching is not found
503
NOT_READY
Server is not ready yet, please try again later
Our server is not ready