Developer

Integration Overview

Authenticate with the Belong API, identify users, and query hubs and events for Belong CheckIn integrations.

Overview

Belong CheckIn is built on the Belong API. This page covers the essentials for integrating with it: authentication, identifying users, and querying hubs and events. For the full REST reference and OpenAPI docs, see API Documentation.

Base URL: https://api.belong.net/api/v3
Interactive docs: https://api.belong.net/api/v3/docs
Backend MCP endpoint: https://api.belong.net/mcp
Public assistant MCP endpoint: https://join.belong.net/functions/v1/belong-agent-mcp/mcp

Authentication: `x-api-key`

All requests authenticate with the x-api-key header. Do not use Authorization: Bearer.

const response = await fetch('https://api.belong.net/api/v3/events', {
  method: 'GET',
  headers: {
    'x-api-key': userApiKey,
    'Content-Type': 'application/json',
  },
})

The same API key works for all endpoints, including MCP operations, /me, and /me/crypto-addresses. See Getting an API Key to create one.

MCP endpoint choice

CheckIn uses a two-tier MCP structure:

Surface	Use it for	Auth
`https://join.belong.net/functions/v1/belong-agent-mcp/mcp`	External assistants and public AI connectors that need event, hub, venue, check-in, bracelet, reservation, and signing-link workflows	OAuth 2.1 with email-code sign-in and scoped permissions
`https://api.belong.net/mcp`	Trusted backend integrations and first-party services that need raw Belong API, event, NFT, and transaction primitives	`x-api-key`

Do not expose the backend API-key MCP as a public assistant connector. Public assistants should use the OAuth MCP gateway, which audits tool calls and sends sensitive wallet or payment work to a Belong confirmation link.

Identifying the user

To find which user a request belongs to (for filtering hubs and events by ownership), call /api/auth/get-session:

const res = await fetch('https://api.belong.net/api/auth/get-session', {
  headers: { 'x-api-key': userApiKey },
})
const { user } = await res.json()
const belongUserId = user.id // Mongo-style ObjectID, e.g. "507f1f77bcf86cd799439011"

The Belong user ID is a Mongo-style ObjectID — not a UUID. If your app stores its own user IDs (for example a database UUID), keep them separate: never compare your internal IDs to Belong's ownerId / membersIDs.

Profile endpoints

Endpoint	Returns
`GET /api/v3/me`	The authenticated user's profile
`GET /api/v3/me/crypto-addresses`	The user's linked crypto addresses (`address`, `chainId`, `connector`)

Hubs & events

Filtering "My Hubs"

Fetch hubs with the user's API key, then filter by the Belong user ID:

const userHubs = allHubs.filter(hub =>
  hub.ownerId === belongUserId ||
  (Array.isArray(hub.membersIDs) && hub.membersIDs.includes(belongUserId))
)

For a Discover view (public hubs the user hasn't joined), fetch a larger batch (50+) and filter out the user's own hubs — a small page may contain only the user's hubs and leave nothing to discover.

Connecting events to a hub

Use connectEventIds (additive, de-duplicates automatically) rather than replacing the whole categorySubEventIDs array:

await fetch(`https://api.belong.net/api/v3/hubs/${hubId}`, {
  method: 'PUT',
  headers: { 'Content-Type': 'application/json', 'x-api-key': apiKey },
  body: JSON.stringify({ connectEventIds: [eventId] }),
})

Query parameters

Parameter	Type	Notes
`take`	integer (1–100, default 20)	Items per page — use `take`, not `limit`
`page`	integer	1-based page index
`cursor`	string	Cursor from a previous page
`sort`	`createdAt` \| `updatedAt`	Default `createdAt`
`order`	`asc` \| `desc`	Default `desc`
`search`	string	Case-insensitive across name, slug, description
`hubType`	`group` \| `nftCollection`	Filter by hub type
`status`	`PUBLISHED` \| `INCOMPLETE`	Filter by status

The private parameter pitfall. It expects a boolean, but query strings are always strings — sending private=false causes a 400. Omit the parameter entirely and user-specific access rules apply automatically.

Common mistakes

Using Authorization: Bearer instead of x-api-key
Comparing your internal user IDs to Belong's Mongo-style IDs
Using limit instead of take for pagination
Sending private=false as a string (omit it instead)
Fetching too few hubs for a Discover view

API Documentation — full REST reference
API Reference — CheckIn edge functions
MCP Tools

Edit this pageorReport an issue

Whitepaper

Belong CheckIn whitepaper covering platform, economics, and architecture.

API Reference

The serverless functions that power Belong CheckIn's AI chat, transcription, and tool discovery.