Skip to content
Bonfire Docs
Docs

tutorial

Your first API call

This tutorial gets you from zero to an authenticated request against the Bonfire REST API in about 5 minutes. You'll generate a key and call /api/v1/me to confirm it works.

Prerequisites

  • You're an owner or admin of a Bonfire community (API keys are created in Admin).
  • curl installed locally.

1. Generate an API key

  1. Open the Admin panel and go to Admin → API Keys.
  2. Click New API key.
  3. Give it a clear name (for example, local-dev).
  4. Copy the key immediately — it's shown only once. Store it somewhere safe.

Treat the key like a password. It carries your community's permissions. Revoke it from Admin → API Keys if it leaks.

2. Set the base URL

All v1 endpoints live under /api/v1 on your community's address:

https://<your-community>.onbonfire.com/api/v1

Replace <your-community> with your subdomain (or use your custom domain).

3. Call /api/v1/me

Send your key as a Bearer token in the Authorization header:

curl https://<your-community>.onbonfire.com/api/v1/me \
  -H "Authorization: Bearer YOUR_API_KEY"

A successful response returns JSON describing the authenticated context, for example:

{
  "id": "usr_123",
  "name": "Ada Lovelace",
  "role": "admin",
  "community": "trail-runners"
}

If you get 401 Unauthorized, recheck the header spelling and that you copied the full key.

4. Where to go next

  • Explore other endpoints under /api/v1.
  • Set up webhooks to receive events.
  • Pilot the native MCP server at /api/mcp directly from Claude.
  • Manage your whole community as code with the CLI (community-as-code YAML).

Related

  • Launch your community
  • Invite your first members
  • Join a community

FAQ

Where do I create and revoke keys? In Admin → API Keys. Keys can be revoked at any time; revoking takes effect immediately.

Why is my key only shown once? For security, Bonfire stores a hash, not the raw key. If you lose it, generate a new one.

Which auth scheme does the API use? Bearer tokens: Authorization: Bearer YOUR_API_KEY. There's no separate signing step.

Can members create API keys? No. Only owner and admin roles can access Admin → API Keys.

Can I use the same key with the MCP server and CLI? Yes. The same Bearer key authenticates the REST API, the MCP server at /api/mcp, and the CLI.