Invite API

Create and verify invite tokens for gating access to the Agentbot platform.

Invite tokens are 64-character hex strings generated from crypto.randomBytes(32). The older 12-character code format is deprecated — see legacy format below.

Authentication

Endpoint	Auth required
`POST /api/invite`	Session (any authenticated user)
`POST /api/invites/verify`	None
`GET /api/admin/invites`	Session (admin only)
`POST /api/admin/invites`	Session (admin only)

Create invite

POST /api/invite

Creates an invite token linked to your account. Requires an authenticated session.

Request body

Field	Type	Required	Description
`name`	string	Yes	Display name for the invite recipient. Validated against injection patterns.

Response

{
  "success": true,
  "inviteUrl": "https://agentbot.sh/invite?token=abc123...&name=Alice",
  "token": "a1b2c3d4...64 hex characters"
}

Field	Type	Description
`success`	boolean	Whether the invite was created
`inviteUrl`	string	Full URL the recipient can use to accept the invite
`token`	string	64-character hex token

Errors

Code	Description
400	Name is missing or contains invalid characters
401	Not authenticated
404	User not found
500	Failed to create invite

Verify invite

POST /api/invites/verify

Verifies an invite token and returns invite details. No authentication required. Tokens must be in the 64-character hex format.

Request body

Field	Type	Required	Description
`token`	string	Yes	64-character hex invite token

Response (valid)

{
  "valid": true,
  "plan": "headliner",
  "audience": "headliner",
  "email": "invitee@example.com"
}

Field	Type	Description
`valid`	boolean	Whether the token is valid
`plan`	string	Plan tier assigned to the invite. Returns `"headliner"` when the invite audience is `headliner`, otherwise `"solo"`.
`audience`	string \| undefined	Invite audience tier: `headliner`, `guest`, or `partner`. Omitted when the invite was verified by token format alone.
`email`	string \| null \| undefined	Email associated with the invite, when stored. Omitted when the invite was verified by token format alone.
`note`	string \| undefined	Present only when the invite was verified by token format alone (database model pending). Omitted when the invite was verified against the database.

The branded headliner landing page at /basefm/headliner calls this endpoint to confirm the invite before pointing DJs to redemption and the DJ stream panel. It reads audience and email from the response to display issued-to details.

Errors

Code	Description
400	Token is missing, not a string, or not in valid 64-character hex format
404	Invite not found
410	Invite has already been used or has expired
500	Verification failed

List invites (admin)

GET /api/admin/invites

Returns the most recent invites with summary counts. Requires an authenticated session with an admin email address. Records are persisted in the database, so invites survive process restarts and remain auditable.

Response

{
  "invites": [
    {
      "code": "a1b2c3d4...64 hex characters",
      "email": "invitee@example.com",
      "audience": "headliner",
      "createdAt": "2026-03-25T21:00:00.000Z",
      "expiresAt": "2026-06-25T21:00:00.000Z",
      "status": "active"
    }
  ],
  "total": 1,
  "active": 1
}

Field	Type	Description
`invites`	array	List of invites, ordered by creation time descending. Up to 200 entries.
`invites[].code`	string	64-character hex invite token
`invites[].email`	string \| null	Email the invite was created for
`invites[].audience`	string	Invite audience tier: `headliner`, `guest`, or `partner`
`invites[].createdAt`	string	ISO 8601 creation timestamp
`invites[].usedAt`	string \| undefined	ISO 8601 timestamp when the invite was redeemed
`invites[].expiresAt`	string \| undefined	ISO 8601 expiration timestamp. Omitted if the invite has no expiry.
`invites[].status`	string	One of `active`, `used`, or `expired`. An invite is `expired` when `expiresAt` has passed and the invite has not been used.
`total`	number	Total number of invites returned
`active`	number	Number of invites with status `active`

Errors

Code	Description
403	Not authorized (requires admin)
500	Failed to retrieve invites

Create invite (admin)

POST /api/admin/invites

Creates an invite for a specific email address and persists it to the database. Requires an authenticated session with an admin email address.

Request body

Field	Type	Required	Description
`email`	string	Yes	Email address to associate with the invite. Must be a valid email format; lower-cased on save.
`audience`	string	No	Invite audience tier. One of `headliner`, `guest`, or `partner`. Defaults to `headliner`.
`expiresAt`	string	No	ISO 8601 timestamp at which the invite expires. Omit for an invite with no expiry.

Response

{
  "success": true,
  "invite": {
    "code": "a1b2c3d4...64 hex characters",
    "email": "invitee@example.com",
    "audience": "headliner",
    "createdAt": "2026-03-25T21:00:00.000Z",
    "expiresAt": "2026-06-25T21:00:00.000Z",
    "status": "active"
  },
  "code": "a1b2c3d4...64 hex characters",
  "email": "invitee@example.com",
  "audience": "headliner",
  "inviteUrl": "https://agentbot.sh/invite?token=a1b2c3d4..."
}

Returns HTTP 201 Created on success.

Field	Type	Description
`success`	boolean	Whether the invite was created
`invite`	object	The created invite record. Same shape as items in the list invites response.
`code`	string	64-character hex invite token (mirrors `invite.code`)
`email`	string	Email the invite was created for (mirrors `invite.email`)
`audience`	string	Invite audience tier (mirrors `invite.audience`)
`inviteUrl`	string	Full URL the recipient can use to accept the invite

Errors

Code	Description
400	Email is missing, not a valid email address, `audience` is not one of the allowed values, or `expiresAt` is not a valid ISO 8601 date
403	Not authorized (requires admin)
500	Failed to create invite

Legacy invite format

The previous invite system used 12-character hex codes with POST /api/invite/generate and POST /api/invite/validate. These endpoints are deprecated. Migrate to the new endpoints above.

Deprecated: generate invite code

POST /api/invite/generate

Previously generated a 12-character hex invite code. Replaced by POST /api/invite (session auth) and POST /api/admin/invites (admin session auth).

Deprecated: validate invite code

POST /api/invite/validate

Previously validated and consumed a 12-character invite code. Replaced by POST /api/invites/verify, which accepts 64-character hex tokens and returns valid and plan fields.

Getting Started

Core Concepts

Integrations

Core Services

Payments

API Reference

MCP

Security

Invite API

Invite API

Authentication

Create invite

Request body

Response

Errors

Verify invite

Request body

Response (valid)

Errors

List invites (admin)

Response

Errors

Create invite (admin)

Request body

Response

Errors

Legacy invite format

Deprecated: generate invite code

Deprecated: validate invite code

​Invite API

​Authentication

​Create invite

​Request body

​Response

​Errors

​Verify invite

​Request body

​Response (valid)

​Errors

​List invites (admin)

​Response

​Errors

​Create invite (admin)

​Request body

​Response

​Errors

​Legacy invite format

​Deprecated: generate invite code

​Deprecated: validate invite code

Invite API

Authentication

Create invite

Request body

Response

Errors

Verify invite

Request body

Response (valid)

Errors

List invites (admin)

Response

Errors

Create invite (admin)

Request body

Response

Errors

Legacy invite format

Deprecated: generate invite code

Deprecated: validate invite code