The player provides their ZooGamesID and 2FA token, and if the credentials are valid, the server grants access for the user to log in.
A user's session in the application has an expiration time of 120 minutes. After this period, the session will expire, and the user will need to log in again.
If the user wants to extend the session and prevent it from expiring, they can use the Keep-alive API. By making a request to the Keep-alive API within the session's duration, the session will be refreshed, and the expiration time will be extended.
To gain insights into how authentication works on Zoo.Games, you can explore our open-source Telegram AUTH web app. It will provide you with a clear understanding of the authentication process implemented on the Zoo.Games platform.
To ensure compatibility with the API, please note that only lowercase ZooGamesIDs are supported. When communicating with the API, please convert any uppercase letters in the ZooGames ID to lowercase. You can maintain the appearance of capital letters in your game, but the actual communication with the API should use lowercase characters.
To authenticate and handle login and logout functionality, you need to follow these steps:
Login and Logout
by installing the SDK and utilizing the signData() function, you can generate the SignedSignatureFromPayload (HMAC signature) for authentication purposes in the ZooGames API requests
Login API - To Login user and return JWT token as a session token
POSTAPI_END_POINT_URL/API_KEY/session/login
SDK Preparation
You need to prepare for SignedSignatureFromPayload by
Installing zoo-game-sdk by npm install zoo-game-sdk
Import SDK byimport * as ApiKey from 'zoo-game-sdk/src/auth/apikey/index'
import*as ApiKey from'zoo-game-sdk/src/auth/apikey/index'import axios from'axios';// Initialized API KEY and SECRET KEYconstAPI_KEY='YourApiKey';constSEC_KEY='YourSecretKey';// Signing body data with HMAC signinglet body = {username:"myusername", token:"123456"};let bodyMessage =JSON.stringify(body); let hmac =ApiKey.signData(bodyMessage,SEC_KEY); // hmac or SignedSignatureFromPayload // Request by Post Method //let ret =awaitaxios.post(`/api/${API_KEY}/session/login`, body, {headers:{Authorization:`Bearer ${hmac}`}});console.log('ret',ret.data);
IMPORTANT NOTICE:
If a player is authenticated through the PlayPass account, Avoid logging the user out. Such an action can result in the permanent loss of the users linked digital assets.
Logout API - To log out for already log in user
POSTAPI_END_POINT_URL/API_KEY/session/logout
SDK Preparation
You need to prepare for SignedSignatureFromPayload by
Installing zoo-game-sdk by npm install zoo-game-sdk
Import SDK byimport * as ApiKey from 'zoo-game-sdk/src/auth/apikey/index'
import*as ApiKey from'zoo-game-sdk/src/auth/apikey/index'import axios from'axios';// Initialized API KEY and SECRET KEYconstAPI_KEY='YourApiKey';constSEC_KEY='YourSecretKey';// Signing body data with HMAC signinglet body = {jwt: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VybmFtZSI6ImNyeXB0b2Zlbm5lYyIsInByaW1hcnlBZGRyZXNzIjoiMHg2QWI0OTljOEUyZjNDQmM5Qzk5MDM0YjZlMjkxMjE0OTIxMmJFNzcwIiwibWlycm9yQWRkcmVzcyI6IjB4ZTQyNzQxZjI4ZTE1YzU4NzkxMjlGZTVGNzQ5Zjc4NjIzZWU3MTIzNiIsIm1pcnJvckJhbGFuY2UiOiI1NTUuMSIsImNoYWluSWQiOiI4ODgiLCJ2ZXJpZnkyRkFTdWNjZXNzVGltZXMiOjQsImlhdCI6MTY1NjMxMTc4MH0.4EzwI54lVs_9zx2Qy-UhDsVb5PocHIDjxK0cCIxEZko"};
let bodyMessage =JSON.stringify(body); let hmac =ApiKey.signData(bodyMessage,SEC_KEY); // hmac or SignedSignatureFromPayload // Request by Post Method //let ret =awaitaxios.post(`/api/${API_KEY}/session/logout`, body, {headers:{Authorization:`Bearer ${hmac}`}});console.log('ret',ret.data);
Keep-alive
The Keep-Alive feature allows users to extend the expiration time of their session. By making a request to the Keep-Alive API endpoint within the session duration, users can refresh the session and prevent it from expiring.
Keep-alive API - To keep alive (Persistent Session) logged in user
POSTAPI_END_POINT_URL/API_KEY/session/keepAlive
SDK Preparation
You need to prepare for SignedSignatureFromPayload by
Installing zoo-game-sdk by npm install zoo-game-sdk
Import SDK byimport * as ApiKey from 'zoo-game-sdk/src/auth/apikey/index'
import*as ApiKey from'zoo-game-sdk/src/auth/apikey/index'import axios from'axios';// Initialized API KEY and SECRET KEYconstAPI_KEY='YourApiKey';constSEC_KEY='YourSecretKey';// Signing body data with HMAC signinglet body = {username: "myusername", jwt: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VybmFtZSI6ImNyeXB0b2Zlbm5lYyIsInByaW1hcnlBZGRyZXNzIjoiMHg2QWI0OTljOEUyZjNDQmM5Qzk5MDM0YjZlMjkxMjE0OTIxMmJFNzcwIiwibWlycm9yQWRkcmVzcyI6IjB4ZTQyNzQxZjI4ZTE1YzU4NzkxMjlGZTVGNzQ5Zjc4NjIzZWU3MTIzNiIsIm1pcnJvckJhbGFuY2UiOiI1NTUuMSIsImNoYWluSWQiOiI4ODgiLCJ2ZXJpZnkyRkFTdWNjZXNzVGltZXMiOjQsImlhdCI6MTY1NjMxMTc4MH0.4EzwI54lVs_9zx2Qy-UhDsVb5PocHIDjxK0cCIxEZko"};
let bodyMessage =JSON.stringify(body); let hmac =ApiKey.signData(bodyMessage,SEC_KEY); // hmac or SignedSignatureFromPayload // Request by Post Method //let ret =awaitaxios.post(`/api/${API_KEY}/session/keepAlive`, body, {headers:{Authorization:`Bearer ${hmac}`}});console.log('ret',ret.data);
Keep-Alive helps enhance user experience by reducing the need for repeated logins and provides convenience during extended usage periods.
Approve
Approve API enables the creation of in-game vZOO transactions. However, to ensure security and validate the transaction, players are required to re-enter their 2FA (Two-Factor Authentication) credentials.
If the 2FA validation fails or is not provided by the player, the transaction will not be approved and will result in a failure.
Approve API - To request vZOO spending from user mirror address
POSTAPI_END_POINT_URL/API_KEY/session/approve
SDK Preparation
You need to prepare for SignedSignatureFromPayload by
Installing zoo-game-sdk by npm install zoo-game-sdk
Import SDK byimport * as ApiKey from 'zoo-game-sdk/src/auth/apikey/index'
Signing by SDK
let bodyMessage =JSON.stringify(payload);
let hmac = ApiKey.signData(bodyMessage, SEC_KEY);
*Use "hmac" as SignedSignatureFromPayload
Path Parameters
Name
Type
Description
API_KEY*
String
API Key
Headers
Name
Type
Description
authorization*
String
Bearer SignedSignatureFromPayload
Request Body
Name
Type
Description
username*
String
ZooGamesId
jwt*
String
JWT token you got from Login API
approval*
Decimal
vZOO amount for approval (e.g. 0.1)
playSeconds*
Integer
approval expiry in (e.g. 3600)
gameAddress
Address
Address of Game/Project registered Primary Address
import*as ApiKey from'zoo-game-sdk/src/auth/apikey/index'import axios from'axios';// Initialized API KEY and SECRET KEYconstAPI_KEY='YourApiKey';constSEC_KEY='YourSecretKey';// Signing body data with HMAC signinglet body = {username: "myusername", "token":"123456", jwt: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VybmFtZSI6ImNyeXB0b2Zlbm5lYyIsInByaW1hcnlBZGRyZXNzIjoiMHg2QWI0OTljOEUyZjNDQmM5Qzk5MDM0YjZlMjkxMjE0OTIxMmJFNzcwIiwibWlycm9yQWRkcmVzcyI6IjB4ZTQyNzQxZjI4ZTE1YzU4NzkxMjlGZTVGNzQ5Zjc4NjIzZWU3MTIzNiIsIm1pcnJvckJhbGFuY2UiOiI1NTUuMSIsImNoYWluSWQiOiI4ODgiLCJ2ZXJpZnkyRkFTdWNjZXNzVGltZXMiOjQsImlhdCI6MTY1NjMxMTc4MH0.4EzwI54lVs_9zx2Qy-UhDsVb5PocHIDjxK0cCIxEZko","approval":0.1,"playSeconds":3600,"gameAddress": "0xd207d371d7a24F65cE9CcB3C78B58f27DF279Eb2"};
let bodyMessage =JSON.stringify(body); let hmac =ApiKey.signData(bodyMessage,SEC_KEY); // hmac or SignedSignatureFromPayload // Request by Post Method //let ret =awaitaxios.post(`/api/${API_KEY}/session/approve`, body, {headers:{Authorization:`Bearer ${hmac}`}});console.log('ret',ret.data);
Status
The Status API returns the current JWT Payload and verifies whether their JWT is eligible for use in the Settlement API.
Status API - Returns current JWT Payload and verifies current JWT
POSTAPI_END_POINT_URL/API_KEY/session/status
SDK Preparation
You need to prepare for SignedSignatureFromPayload by
Installing zoo-game-sdk by npm install zoo-game-sdk
Import SDK byimport * as ApiKey from 'zoo-game-sdk/src/auth/apikey/index'
Signing by SDK
let bodyMessage =JSON.stringify(payload);
let hmac = ApiKey.signData(bodyMessage, SEC_KEY);
*Use "hmac" as SignedSignatureFromPayload
Path Parameters
Name
Type
Description
API_KEY*
String
API Key
Headers
Name
Type
Description
authorization*
String
Bearer SignedSignatureFromPayload
Request Body
Name
Type
Description
jwt*
String
JWT token you got from Login API
Query String
Name
Type
Description
without_avatar
Boolean
true: To set "avatar" property as "null" to reduce the returning data
import*as ApiKey from'zoo-game-sdk/src/auth/apikey/index'import axios from'axios';// Initialized API KEY and SECRET KEYconstAPI_KEY='YourApiKey';constSEC_KEY='YourSecretKey';// Signing body data with HMAC signinglet body = {jwt: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VybmFtZSI6ImNyeXB0b2Zlbm5lYyIsInByaW1hcnlBZGRyZXNzIjoiMHg2QWI0OTljOEUyZjNDQmM5Qzk5MDM0YjZlMjkxMjE0OTIxMmJFNzcwIiwibWlycm9yQWRkcmVzcyI6IjB4ZTQyNzQxZjI4ZTE1YzU4NzkxMjlGZTVGNzQ5Zjc4NjIzZWU3MTIzNiIsIm1pcnJvckJhbGFuY2UiOiI1NTUuMSIsImNoYWluSWQiOiI4ODgiLCJ2ZXJpZnkyRkFTdWNjZXNzVGltZXMiOjQsImlhdCI6MTY1NjMxMTc4MH0.4EzwI54lVs_9zx2Qy-UhDsVb5PocHIDjxK0cCIxEZko"};
let bodyMessage =JSON.stringify(body); let hmac =ApiKey.signData(bodyMessage,SEC_KEY); // hmac or SignedSignatureFromPayload // Request by Post Method //let ret =awaitaxios.post(`/api/${API_KEY}/session/status`, body, {headers:{Authorization:`Bearer ${hmac}`}});console.log('ret',ret.data);
Login and Approve
When users interact with the Login and Approve API, they are required to provide their login credentials, ZooGamesID and 2FA, to authenticate themselves and gain access to their account. Upon successful authentication, users can proceed to approve in-game transactions.
If the 2FA validation fails or is not provided by the player, the transaction will not be approved and will result in a failure.
Login and Approve API - to Login and Approve at once
import*as ApiKey from'zoo-game-sdk/src/auth/apikey/index'import axios from'axios';// Initialized API KEY and SECRET KEYconstAPI_KEY='YourApiKey';constSEC_KEY='YourSecretKey';// Signing body data with HMAC signinglet body = {username:"myusername","token":"123456","approval":0.1,"playSeconds":3600,"gameAddress":"0xd207d371d7a24F65cE9CcB3C78B58f27DF279Eb2"};let bodyMessage =JSON.stringify(body); let hmac =ApiKey.signData(bodyMessage,SEC_KEY); // hmac or SignedSignatureFromPayload // Request by Post Method //let ret =awaitaxios.post(`/api/${API_KEY}/session/loginAndApprove`, body, {headers:{Authorization:`Bearer ${hmac}`}});console.log('ret',ret.data);
