
Authenticating users on your application using the ZKcandy API is a quick and easy process. Using just an email address, the Candy API will create an new Passport ID for your user if they don't have one already and then proceed to send the user a One-Time Password (OTP) via email. Once entered, the Candy API will return a JSON Web Token (JWT) that you can use to authenticate the user securely in your web app.
A Candy API key
A gameId for your application
A login interface for the user to input their email
Go to the Candy API dashboard at https://app.zkcandyapi.com/ and login with your Ethereum wallet.
Alternatively you can also login with your email. Check your inbox for a single-use login link. The OTP is already contained within this link so simply follow the link to login to the dashboard.
Once you are logged in, click on “Profile” on the top right of the interface. This will reveal your Client ID and API Key.
Your API is considered a secret and should be kept private. Be mindful when committing code to public repositories to prevent your API key from being published.
The Candy API also requires a gameId when making calls. Despite its name, this applies to any unique application using the Candy API regardless whether it is a game or not.
Login to the Candy API dashboard at https://app.zkcandyapi.com/ and go to the “Games” tab on the top-left navigation bar.
If you have not already registered your game or application, click on “Create Game”. Enter a name for your game and provide the linked NFT contract address for your game/app if you have made one previously through the Candy API.
Once you have created the game, click on the “View Games” tab to see your game and its corresponding gameId.
Before proceeding, your game/app will need to register its frontend URL on the Candy API Dashboard.
Login to the Candy API Dashboard at app.zkcandyapi.com and navigate to the “Games” tab on the top-left navigation bar. You should see your list of games and their corresponding gameId. If not, click on the “View Games” tab.
To the right of the gameId you should see a button labelled “Add Frontend URL”. Click on this and enter your game/app’s frontend URL.
At the moment you can only set the Frontend URL for your game once. If you are testing authentication on a staging environment, please create a new game on the Candy API dashboard and use the
gameIdfrom that game. If you set the incorrect Frontend URL for your game, you will need to create a new game on the Candy API dashboard to get a newgameId.
The Frontend URL is necessary as the login link sent to the user via email will include the OTP in its parameters.
The API endpoint for authentication is https://otpauth.zkcandyapi.com.
The process of acquiring your JWT requires two methods to be called. After your user enters their email into the login modal, POST a request to the authentication endpoint with the following parameters in the request body:
action: generate
apiKey: Your API key from the Candy API Dashboard
gameId: Your gameId from the Candy API Dashboard
email: Email address of the user
The API will return a success response once the email containing the login link is sent to the user.
The user will receive an email with a link that looks like http://your.frontend.url/login?email=zook%40zkcandy.io&otp=123456. This link will be populated with the Frontend URL you bound to your gameId in the above step.
Your app should always check for and parse both the OTP and Email from the window.location and/or URL path. If an OTP and Email address are present, make another POST request to the endpoint with the following parameters in the request body:
Make sure to parse the URL-encoded “@” sign which is encoded as
%40.
action: verify
apiKey: Your API key from the Candy API Dashboard
gameId: Your gameId from the Candy API Dashboard
email: Email address parsed from the window.location
otp: The six-digit OTP parsed from the window.location
If the OTP is correct, the API will return a success response along with the JWT to authenticate your user.
You can now use the JWT to authenticate users on your game or application. In this blog, we will cover more ways to make use of the Candy API and how it can supercharge your game with ZKcandy’s gaming-engineered Layer-2.
For more documentation on the the Candy API and the ZKcandy Gaming SDKrefer to the documentation at docs.zkcandyapi.com.
As covered by the ZKcandy team in this recent blog post, the decision by Telegram to limit blockchain connectivity with their Mini-App ecosystem to The Open Network (TON) blockchain has left several EVM blockchain games and their developers with no choice but to either adopt TON or to move their application to another ecosystem altogether.
While the TON blockchain has a solid usecase in itself, it is unfortunately not EVM-compatible. As such, developers who opt for the former option of adopting TON will be faced with the challenge of rewriting some of their application codebase to be able to work with TON. This includes having to learn FunC - the contract programming language of the TON blockchain.
ZKcandy is a ZKEVM Layer-2 which is high-level EVM-compatible. Solidity and Vyper devs only need to compile their code with the correct tooling to be able to deploy contracts to this gaming-optimised Layer-2 to benefit from lower gas fees and faster transactions, all secured by the Ethereum Mainnet.
The approach taken by ZKcandy in the light of Telegram's new rules was to migrate existing Telegram Mini-Apps developed both in-house and also by partners to a Progressive Web Application (PWA) ecosystem. As blockchain games need to be online to function, the PWA platform makes the most sense for mobile games that utilise blockchain technology. Authenticating PWA users via the Candy Passport using the method described in this article provides for an excellent way to move forward with this new direction.
We hope you and your application(s) will be able to benefit from this quick and easy authentication method. As ZKcandy continues to build an open gaming ecosystem, there will be more features that Candy Passport users will be able to benefit from. Subscribe to stay in the know about these exciting new developments as they come!

Authenticating users on your application using the ZKcandy API is a quick and easy process. Using just an email address, the Candy API will create an new Passport ID for your user if they don't have one already and then proceed to send the user a One-Time Password (OTP) via email. Once entered, the Candy API will return a JSON Web Token (JWT) that you can use to authenticate the user securely in your web app.
A Candy API key
A gameId for your application
A login interface for the user to input their email
Go to the Candy API dashboard at https://app.zkcandyapi.com/ and login with your Ethereum wallet.
Alternatively you can also login with your email. Check your inbox for a single-use login link. The OTP is already contained within this link so simply follow the link to login to the dashboard.
Once you are logged in, click on “Profile” on the top right of the interface. This will reveal your Client ID and API Key.
Your API is considered a secret and should be kept private. Be mindful when committing code to public repositories to prevent your API key from being published.
The Candy API also requires a gameId when making calls. Despite its name, this applies to any unique application using the Candy API regardless whether it is a game or not.
Login to the Candy API dashboard at https://app.zkcandyapi.com/ and go to the “Games” tab on the top-left navigation bar.
If you have not already registered your game or application, click on “Create Game”. Enter a name for your game and provide the linked NFT contract address for your game/app if you have made one previously through the Candy API.
Once you have created the game, click on the “View Games” tab to see your game and its corresponding gameId.
Before proceeding, your game/app will need to register its frontend URL on the Candy API Dashboard.
Login to the Candy API Dashboard at app.zkcandyapi.com and navigate to the “Games” tab on the top-left navigation bar. You should see your list of games and their corresponding gameId. If not, click on the “View Games” tab.
To the right of the gameId you should see a button labelled “Add Frontend URL”. Click on this and enter your game/app’s frontend URL.
At the moment you can only set the Frontend URL for your game once. If you are testing authentication on a staging environment, please create a new game on the Candy API dashboard and use the
gameIdfrom that game. If you set the incorrect Frontend URL for your game, you will need to create a new game on the Candy API dashboard to get a newgameId.
The Frontend URL is necessary as the login link sent to the user via email will include the OTP in its parameters.
The API endpoint for authentication is https://otpauth.zkcandyapi.com.
The process of acquiring your JWT requires two methods to be called. After your user enters their email into the login modal, POST a request to the authentication endpoint with the following parameters in the request body:
action: generate
apiKey: Your API key from the Candy API Dashboard
gameId: Your gameId from the Candy API Dashboard
email: Email address of the user
The API will return a success response once the email containing the login link is sent to the user.
The user will receive an email with a link that looks like http://your.frontend.url/login?email=zook%40zkcandy.io&otp=123456. This link will be populated with the Frontend URL you bound to your gameId in the above step.
Your app should always check for and parse both the OTP and Email from the window.location and/or URL path. If an OTP and Email address are present, make another POST request to the endpoint with the following parameters in the request body:
Make sure to parse the URL-encoded “@” sign which is encoded as
%40.
action: verify
apiKey: Your API key from the Candy API Dashboard
gameId: Your gameId from the Candy API Dashboard
email: Email address parsed from the window.location
otp: The six-digit OTP parsed from the window.location
If the OTP is correct, the API will return a success response along with the JWT to authenticate your user.
You can now use the JWT to authenticate users on your game or application. In this blog, we will cover more ways to make use of the Candy API and how it can supercharge your game with ZKcandy’s gaming-engineered Layer-2.
For more documentation on the the Candy API and the ZKcandy Gaming SDKrefer to the documentation at docs.zkcandyapi.com.
As covered by the ZKcandy team in this recent blog post, the decision by Telegram to limit blockchain connectivity with their Mini-App ecosystem to The Open Network (TON) blockchain has left several EVM blockchain games and their developers with no choice but to either adopt TON or to move their application to another ecosystem altogether.
While the TON blockchain has a solid usecase in itself, it is unfortunately not EVM-compatible. As such, developers who opt for the former option of adopting TON will be faced with the challenge of rewriting some of their application codebase to be able to work with TON. This includes having to learn FunC - the contract programming language of the TON blockchain.
ZKcandy is a ZKEVM Layer-2 which is high-level EVM-compatible. Solidity and Vyper devs only need to compile their code with the correct tooling to be able to deploy contracts to this gaming-optimised Layer-2 to benefit from lower gas fees and faster transactions, all secured by the Ethereum Mainnet.
The approach taken by ZKcandy in the light of Telegram's new rules was to migrate existing Telegram Mini-Apps developed both in-house and also by partners to a Progressive Web Application (PWA) ecosystem. As blockchain games need to be online to function, the PWA platform makes the most sense for mobile games that utilise blockchain technology. Authenticating PWA users via the Candy Passport using the method described in this article provides for an excellent way to move forward with this new direction.
We hope you and your application(s) will be able to benefit from this quick and easy authentication method. As ZKcandy continues to build an open gaming ecosystem, there will be more features that Candy Passport users will be able to benefit from. Subscribe to stay in the know about these exciting new developments as they come!
<100 subscribers
<100 subscribers
Share Dialog
Share Dialog
No comments yet