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
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.raveculture.xyz/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
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": "solo"
}
| Field | Type | Description |
|---|
valid | boolean | Whether the token is valid |
plan | string | Plan tier assigned to the invite. Currently always "solo". |
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 email field was removed from the verify response. The invite codes table does not store an email column. If you previously relied on this field, use a separate user lookup after verification.
Errors
| Code | Description |
|---|
| 400 | Token is missing, not a string, or not in valid 64-character hex format |
| 404 | Invite not found or expired |
| 410 | Invite has already been used |
| 500 | Verification failed |
List invites (admin)
Returns all invites with summary counts. Requires an authenticated session with an admin email address.
Response
{
"invites": [
{
"code": "a1b2c3d4...64 hex characters",
"email": "invitee@example.com",
"createdAt": "2026-03-25T21:00:00.000Z",
"status": "active"
}
],
"total": 1,
"active": 1
}
| Field | Type | Description |
|---|
invites | array | List of all invites |
invites[].code | string | 64-character hex invite token |
invites[].email | string | Email the invite was created for |
invites[].createdAt | string | ISO 8601 creation timestamp |
invites[].usedAt | string | undefined | ISO 8601 timestamp when the invite was used |
invites[].status | string | One of active, used, or expired |
invites[].userId | string | undefined | User ID of the person who redeemed the invite |
total | number | Total number of invites |
active | number | Number of currently active invites |
Errors
| Code | Description |
|---|
| 403 | Not authorized (requires admin) |
| 500 | Failed to retrieve invites |
Create invite (admin)
Creates an invite for a specific email address. 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 |
Response
{
"success": true,
"code": "a1b2c3d4...64 hex characters",
"email": "invitee@example.com",
"inviteUrl": "https://agentbot.raveculture.xyz/invite?token=a1b2c3d4..."
}
| Field | Type | Description |
|---|
success | boolean | Whether the invite was created |
code | string | 64-character hex invite token |
email | string | Email the invite was created for |
inviteUrl | string | Full URL the recipient can use to accept the invite |
Errors
| Code | Description |
|---|
| 400 | Email is missing |
| 403 | Not authorized (requires admin) |
| 500 | Failed to create invite |
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
POST /api/invite (session auth) and POST /api/admin/invites (admin session auth).
Deprecated: validate invite code
POST /api/invite/validate
POST /api/invites/verify, which accepts 64-character hex tokens and returns valid and plan fields.
