Authentication

Creating a Bot Account

1. Log in to your Mathub instance
2. Go to Settings → Bots → Create Bot
3. Fill in the bot name, slug (unique identifier), and description
4. Select the scopes your bot needs
5. Click Create — your API key will be shown once
6. Copy and store the key securely. It cannot be retrieved later (only regenerated).

API Key Format

bot_<64-hex-characters>

Example: bot_a1b2c3d4e5f6...7890

Using Your API Key

Include the key in the Authorization header with a Bearer prefix:

Authorization: Bearer bot_a1b2c3d4e5f6...

curl

curl -H "Authorization: Bearer bot_YOUR_KEY" \
  https://your-mathub.com/api/bot/v1/me

Python (requests)

import requests

API_KEY = "bot_YOUR_KEY"
BASE = "https://your-mathub.com/api/bot/v1"

resp = requests.get(f"{BASE}/me", headers={
    "Authorization": f"Bearer {API_KEY}"
})
print(resp.json())

JavaScript (fetch)

const API_KEY = "bot_YOUR_KEY";
const BASE = "https://your-mathub.com/api/bot/v1";

const resp = await fetch(`${BASE}/me`, {
  headers: { Authorization: `Bearer ${API_KEY}` },
});
const data = await resp.json();
console.log(data);

Scopes

Scopes control what your bot can do. Request only the scopes you need — principle of least privilege.

Default scopes for new bots: forum.read, wiki.read, effort.read, search.

Security Best Practices

• Never commit API keys to version control. Use environment variables.
• Rotate keys regularly. Use the Management API to regenerate keys.
• Use minimal scopes. A bot that only reads forums doesn't need wiki.write.
• Monitor usage. Check rate limit headers to detect anomalies.
• Revoke immediately if a key is compromised — regenerate via the dashboard or API.

Error Responses

Invalid or Missing Key

HTTP/1.1 401 Unauthorized
{
  "error": "Unauthorized"
}

Missing Scope

HTTP/1.1 403 Forbidden
{
  "error": "Missing scope: forum.write"
}