AUTHENTICATION

📘 Authentication – `TOKEN_AUTH`

Each API is assigned a unique authentication token, which can be obtained from the API section of your nandbox account.

📌 Generating a new token will immediately invalidate any previously issued token.

👍🏻 Remember — a happy API is an authenticated API!

1️⃣ Overview

All requests to the nandbox API require authentication via a unique token.

Requests are sent as JSON objects over a WebSocket session.

You must obtain an authentication token before making any API calls.

Generating a new token invalidates any previous token immediately.

📌 The first request over the WebSocket session must always be an authentication request.

2️⃣ Establishing a WebSocket Connection

To communicate with the nandbox API, connect using WebSocket.

✅ API Server WebSocket URL Format:

plain text
wss://<nandboxBotServer>:<port>/nandbox/api/

✅ Example Connection:

plain text
wss://w1.nandbox.net:5020/nandbox/api/

📌 Once connected, send an authentication request using your API token.

3️⃣ Token Authentication Request (`TOKEN_AUTH`)

After establishing a WebSocket connection, authenticate your session using the TOKEN_AUTH method.

✅ Example Authentication Request:

json
{
  "method": "TOKEN_AUTH",
  "rem": "true",
  "token": "90091784056528980:0:odIgBOQZ4lVpqSIuxpQlGzmse3hwsS"
}

📌 Fields Explanation:

Field	Type	Required	Description
`method`	String	Yes	`"TOKEN_AUTH"` (indicates authentication request).
`rem`	Boolean	Optional	If `"true"`, authentication remains active until manually revoked.
`token`	String	Yes	Your unique API authentication token.

java

public static final String TOKEN = "90091784169275314:0:h8UbS2NPBocFGQ58U2yheNBp3LUQe1";
public class MyFirstBot {

	public static void main(String[] args) throws Exception {
		NandboxClient client = NandboxClient.get();
		client.connect(TOKEN, new Nandbox.Callback() {
			Nandbox.Api api = null;

			@Override
			public void onConnect(Api api) {
				// it will go here if the bot connected to server successfuly 
				System.out.println("Authenticated");
				this.api = api;
			}

			@Override
			public void onReceive(IncomingMessage incomingMsg) {
			// it will go here if the bot received any message 
			}
			// implement other nandbox.Callback() as per your bot need .
		});
	}
}

javascript
// put your provided token
const TOKEN = "<PUT_YOUR_PROVIDED_TOKEN>";
const config = {
    URI: "<PUT_YOUR_PROVIDED_URI>",
    DownloadServer: "<PUT_YOUR_PROVIDED_DOWNLOAD_SERVER_URL>",
    UploadServer: "<PUT_YOUR_PROVIDED_UPLOAD_SERVER_URL>"
}


var client = NandBoxClient.get(config);
var nandbox = new NandBox();
var nCallBack = nandbox.Callback;
var api = null;


nCallBack.onConnect = (_api) => {
    // it will go here if the bot connected to the server successfully 
    api = _api;
    console.log("Authenticated");
    sendBotMenuWithNavigationButton(Nand.BOT_ID);
}

client.connect(TOKEN, nCallBack);

python
CONFIG_FILE = "/config.json"

f = open(CONFIG_FILE)
config = json.load(f)
f.close()

client = NandboxClient.get(config)

nandbox = Nandbox()

napi = nandbox.Api()
class nCallBack(nandbox.Callback):
    def on_connect(self, api):
        global napi
        napi = api
        print("Authenticated")

    
callBack = nCallBack()
client.connect(config['Token'], callBack)

🔹 Key Notes:

Your API token is obtained through the "Get Token" option in the bot chat.

Regenerating a token will instantly revoke all previous tokens.

Upon successful authentication, the WebSocket session is ready for API requests.

4️⃣ Sending API Requests After Authentication

After successful authentication, you can send API requests such as:

✅ Send Messages (sendMessage)

✅ Manage Users (addToWhitelist, removeFromBlacklist)

✅ Upload & Download Media (uploadMedia, downloadMedia)

5️⃣ Receiving Authentication Response

Upon successful authentication, you receive a confirmation response:

✅ Example Success Response:

json
{
  "method": "TOKEN_AUTH_OK",
  "name": "My First API",
  "ID": "90091784056528980",
  "reference": 15269906159119,
  "date": 1533216558322
}

✅ Example Error Response (Invalid Token):

json
{
  "method": "error",
  "code": "100099"
}

📌 Handling Authentication Errors:

If you receive a 100099 Unauthorized error, re-authenticate with a valid token.

If your token expires, obtain a new one via nandbox web account.