Authentication

The API token tells Sukson which bot is calling. Every request to https://api.sukson.dev/v1 sends the bot’s token in the Authorization header as a Bearer token.

GET /v1/me HTTP/1.1
Host: api.sukson.dev
Authorization: Bearer skbot_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

• The token starts with skbot_ followed by 256 random bits.
• Sukson stores only its SHA-256 hash, not the token itself. So the token is shown once, when it’s created or reissued, and can’t be recovered.
• One token belongs to one bot. That bot is me in every endpoint.

When the token doesn’t work

HTTP	code	Meaning
401	INVALID_TOKEN	No token, a malformed one, a replaced one, or the bot was deleted. The answer has WWW-Authenticate: Bearer realm="api.sukson.dev".
403	BOT_DISABLED	Sukson staff switched the bot off or banned it. (A deleted bot’s token answers 401 INVALID_TOKEN.)
503	SERVICE_UNAVAILABLE	Tokens can’t be checked right now. Try again later.

Rotate the token

Issue a new token on the bot’s page at member.sukson.com/bots.

1. Issue the new token and copy it straight away.
2. Update your server’s configuration and deploy.
3. The old token stops working as soon as the new one is issued. A few requests may still pass for up to about 30 seconds while caches clear.

Rotate immediately if you suspect a leak: a token committed to git, written to a log, or known to someone who left.

The token and the webhook secret are different

Your bot uses the API token to call the API. You use the webhook secret to check the events Sukson sends you. The webhook secret changes every time you set a new webhook URL (webhooks).

Keep the token safe

• Store it in a secret manager or an environment variable. Never hard-code it or commit it.
• Call the API from servers only. Never ship the token in a mobile app, browser code or any file users can download. The API has no CORS anyway.
• Don’t log the Authorization header or URLs that contain the token.
• Each bot has its own token: several bots means several tokens.
• Always call https://. If you ever called http:// by mistake, the token may have travelled unencrypted: rotate it.