Bot / Integration Tokens

Alfa Club supports per-user bot tokens — long-lived API credentials that act on your behalf, scoped narrowly to "send chat messages in rooms you hold a key in." Use them when you want to wire up a bot, a webhook, or any external automation that needs to post to a chat without keeping a live user session open.

This is the recommended replacement for keeping a Privy session warm and reusing the resulting JWT — that approach is fragile (sessions drop, tokens rotate, scope is unbounded). Bot tokens are explicit, revocable, and rate-limited.

Before you start

A few things to understand:

• The bot acts as you. Messages it sends appear under your username and avatar (with a small 🤖 badge so other keyholders can tell). Anything the bot says, you said. Treat the token like a password.
• The bot inherits your room access. If you hold a key in room 42, the bot can post in room 42. Sell the key — the bot loses access on the next request, automatically. Buy a new key elsewhere — the bot can post there too.
• One scope: messages:send. Bots cannot trade, stake, bridge, manage rooms, or do anything else.
• Tokens are private. They are shown exactly once, when created. Alfa Club only stores a SHA-256 hash; nobody (including support) can recover a token after creation. If you lose it, revoke and create a new one.

Creating a token

1. Open the app and sign in
2. Settings → Developer → API Tokens
3. Click Create token, give it a descriptive name (e.g. analytics-bot, discord-relay), and submit
4. Copy the plaintext shown in the modal — it starts with alfa_bot_ followed by 32 random characters. You will not see it again.
5. The list view shows the token's prefix, last-used time, and expiry. Use the Revoke button to invalidate it at any time.

You can hold up to 5 active tokens at a time. Revoke unused ones.

API reference

The interactive panel below documents the only endpoint exposed to bot tokens. Use the Test it tab to issue a request directly from the browser — paste your alfa_bot_… token into the Authorization field and a room you hold a key in.

curl -X POST "https://api.alfaclub.app/api/room/42/message" \  -H "Content-Type: application/json" \  -d '{    "body": "hello from my bot"  }'

{
  "ok": true,
  "messageId": "6a7dccc8-0000-4000-8000-000000000000",
  "deduped": false
}

{
  "error": "invalid_body"
}

{
  "error": "invalid token"
}

{
  "error": "forbidden"
}

{
  "error": "rate limited (per-token)"
}

{
  "error": "bot tokens disabled"
}

Idempotency

Set an Idempotency-Key header to safely retry network failures without sending duplicates. Repeats of the same (token, key) combination within a 5-minute window return the same messageId and set deduped: true in the response. Different keys are treated as different messages. Keys must be ≤ 128 characters; longer values are silently treated as if no key was sent.

Rate limits

Bot tokens are subject to two independent token-bucket limits:

The per-token bucket is the burst limiter — a bot doing two-or-three sends back-to-back is fine. The per-owner bucket is a backstop against creating many tokens to evade per-token caps.

If you need higher throughput, get in touch — we'd rather raise your cap than have you fight the limiter.

Lifecycle

Security and accountability

A few things worth being explicit about:

• You are accountable for what your bot says. Every bot message is internally attributable to the token that sent it. Other keyholders see your username with a 🤖 badge — they know it's a bot but they associate it with you.
• Spam, harassment, or wash-amplification via bots is grounds for action under the same policies as human posts. Repeated abuse from a single owner can result in losing API token privileges entirely (separate from any room-level moderation).
• If a token leaks, revoke it immediately in Settings → Developer. If you suspect compromise we can identify which messages came from the leaked token vs. legitimate use of your account.
• Never commit a token to a public repo. GitHub's secret scanner can be configured to alert on the alfa_bot_ prefix; we recommend doing so.

What's not supported

Bot tokens are scoped to sending chat messages. They cannot read messages, trade, stake, bridge, manage rooms, or take any other write action.

If you have a specific use case that would benefit from a broader API surface, let us know — that's the strongest signal for what to ship next.