Authentication

Bot API uses a dedicated bot token. User session tokens and bot tokens are different credentials and cannot be used interchangeably.

Authorization header

Send the token in every REST request:

Authorization: Bot bot_xxx

Example:

curl -sS https://ims.buko.app/bot/getMe \
  -X POST \
  -H "Authorization: Bot $BUKO_BOT_TOKEN" \
  -H "Content-Type: application/json"

Bot Gateway uses the same header during the WebSocket upgrade.

Token format

Bot tokens start with bot_.

Tokens are high-entropy secrets. Store them like passwords. If a token leaks, rotate it from the admin console.

Server-side storage

Buko stores a SHA-256 token hash for authentication. Normal third-party bot tokens are not recoverable after creation or rotation. Buko-managed official bots may additionally store an encrypted operational token copy for the official runner.

getMe

POST https://ims.buko.app/bot/getMe

Returns the authenticated bot identity and capability flags.

curl -sS https://ims.buko.app/bot/getMe \
  -X POST \
  -H "Authorization: Bot $BUKO_BOT_TOKEN" \
  -H "Content-Type: application/json"

Example response:

{
  "ok": true,
  "result": {
    "id": "bot_01J...",
    "is_bot": true,
    "display_name": "Buko AI",
    "handle": "buko_ai",
    "avatar_key": null,
    "status": "active",
    "verified": true,
    "official": true,
    "quota_tier": "official",
    "gateway_connection_limit": 1,
    "capabilities": {
      "edit_delete_messages": true
    }
  }
}

Token rotation

When a token is rotated:

• new REST requests must use the new token
• old REST tokens fail immediately
• existing Gateway connections may be closed by the platform or expire through normal connection lifecycle

Agents should reconnect with the latest token after any authentication failure.