Authentication API

Manage user authentication, password resets, wallet sign-in, Farcaster identity, and token gating.

Auth middleware

Protected backend endpoints require a valid JWT in the Authorization header. The middleware verifies the token, attaches user context to the request, and sets the row-level security (RLS) context on the database connection before any query runs.

Request format

curl -X GET https://agentbot.raveculture.xyz/api/instance/user_123 \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

JWT payload

Field	Type	Description
`userId`	string	Unique user identifier
`email`	string	User email address
`role`	string	User role (for example, `user` or `admin`)

Tokens expire after 7 days.

Error responses

HTTP status	Error code	Description
401	`AUTH_REQUIRED`	No `Authorization` header or missing `Bearer` prefix
401	`TOKEN_INVALID`	JWT signature verification failed or token has expired
403	`ADMIN_REQUIRED`	Endpoint requires admin privileges
500	`AUTH_ERROR`	Unexpected error during authentication

After successful authentication, the middleware sets the database-level user context for RLS. All subsequent queries in that request are automatically scoped to the authenticated user’s data. See Security for details.

POST /api/register

Protected by bot detection. Automated or non-browser requests may be rejected.

Request body

Field	Type	Required	Description
`email`	string	Yes	User email address
`password`	string	Yes	Password (minimum 8 characters)
`name`	string	No	Display name (defaults to email if omitted)
`referralCode`	string	No	Alphanumeric referral code that may include hyphens (max 20 characters). Case-insensitive. Both the new user and the referrer receive credit when a valid code is provided.

Response

{
  "id": "user_123",
  "email": "user@example.com",
  "name": "John Doe"
}

Errors

Code	Description
400	Email and password required, invalid email format, password too short, or invalid referral code
403	Request blocked by bot detection
409	User already exists
429	Too many requests

POST /api/auth/callback/credentials

Request body

{
  "email": "user@example.com",
  "password": "securepassword"
}

OAuth providers support automatic account linking. If a user with the same email address already exists, the OAuth account is linked to the existing user on first sign-in. This lets users who originally signed up with email and password add GitHub or Google login without creating a duplicate account.

GitHub

GET /api/auth/github

Redirects to GitHub OAuth flow. Requires GITHUB_CLIENT_ID and GITHUB_CLIENT_SECRET to be configured.

Google

GET /api/auth/google

Redirects to Google OAuth flow. Requires GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET to be configured.

POST /api/auth/callback/wallet

Sign in using an Ethereum wallet via Sign-In with Ethereum (SIWE). This flow is designed for Base smart wallets and supports ERC-6492 signature verification for pre-deployed wallets.

How it works

The client opens the Base Account SDK popup and requests a SIWE signature on Base Mainnet (chain ID 0x2105).
The signed SIWE message and signature are sent to the wallet NextAuth credentials provider.
The server parses the SIWE message, validates the domain, and verifies the signature.
If no account exists for the wallet address, a new user is created automatically.
If an account with the same email already exists (from a previous OAuth or email sign-up), the wallet is linked to the existing account.

Request body

Field	Type	Required	Description
`message`	string	Yes	The full SIWE message string
`signature`	string	Yes	The wallet signature of the SIWE message (0x-prefixed)

Response

On success, a session cookie is set and the user is redirected to the callback URL. The response follows the standard NextAuth credentials callback flow.

Account linking

When a wallet signs in, the system checks for an existing user by the wallet-derived email address. If a matching user is found (for example, one who previously signed up with email and password or OAuth), the wallet provider is linked to that existing account. This prevents duplicate accounts and lets users access the same data regardless of which sign-in method they use.

Errors

Code	Description
401	Missing message or signature, SIWE domain mismatch, or signature verification failed

The SIWE domain is validated against the configured application URL to prevent replay attacks from other sites.

Get current user

GET /api/settings

Requires session authentication. Returns the current user profile.

Response

{
  "id": "user_123",
  "email": "user@example.com",
  "name": "John Doe",
  "plan": "solo",
  "credits": 0,
  "twoFactorEnabled": false
}

Errors

Code	Description
401	Unauthorized
404	User not found

Update profile

You can update your profile using either POST or PATCH.

POST /api/settings

Request body (POST)

Field	Type	Required	Description
`name`	string	No	New display name
`email`	string	No	New email address (must be unique)

Errors (POST)

Code	Description
400	Invalid email format
401	Unauthorized
409	Email address already in use

PATCH /api/settings

Request body (PATCH)

Field	Type	Required	Description
`name`	string	No	New display name
`notifications`	object	No	Notification preferences

Change password

POST /api/settings/password

Request body

Field	Type	Required	Description
`currentPassword`	string	Yes	Current password
`newPassword`	string	Yes	New password (minimum 8 characters)

Response

{
  "success": true
}

Errors

Code	Description
400	Current and new password required, or password must be at least 8 characters
401	Unauthorized or current password incorrect
404	User not found

Forgot password

POST /api/auth/forgot-password

Protected by bot detection. Rate-limited per IP address. Always returns the same response regardless of whether the email exists, to prevent user enumeration.

Request body

Field	Type	Required	Description
`email`	string	Yes	Account email address

Response

{
  "message": "If an account exists, a reset link has been sent"
}

Errors

Code	Description
400	Email is required, invalid email format, or email service validation error
403	Request blocked by bot detection
429	Too many requests
500	Internal server error

Reset password

POST /api/auth/reset-password

Rate-limited per IP address.

Request body

Field	Type	Required	Description
`token`	string	Yes	Reset token from the email link
`password`	string	Yes	New password (minimum 6 characters)

Response

{
  "message": "Password reset successfully"
}

Errors

Code	Description
400	Token and password are required, password too short (minimum 6 characters), or invalid/expired token
404	User not found
429	Too many requests

Farcaster authentication

Verify Farcaster identity

POST /api/auth/farcaster/verify

GET /api/auth/farcaster/verify

The GET method returns endpoint metadata. The POST method verifies a Farcaster ID token and optionally checks $RAVE token gating on Base.

Request body

Field	Type	Required	Description
`fidToken`	string	Yes	Farcaster ID token
`address`	string	No	Ethereum address for token gating check

Response

{
  "success": true,
  "sessionToken": "base64-encoded-session",
  "address": "0x...",
  "message": "Farcaster verification successful",
  "tokenGated": true,
  "accessLevel": "premium"
}

Errors

Code	Description
401	Missing Farcaster ID token
403	Token gating failed (insufficient `$RAVE` balance). Response includes `required`, `minBalance` fields
500	Verification failed

Refresh Farcaster token

POST /api/auth/farcaster/refresh

GET /api/auth/farcaster/refresh

The GET method returns endpoint metadata.

Request body

Field	Type	Required	Description
`refreshToken`	string	Yes	Base64-encoded refresh token

Response

{
  "success": true,
  "sessionToken": "base64-new-session",
  "expiresIn": 86400,
  "message": "Token refreshed successfully"
}

Errors

Code	Description
400	Missing refresh token
401	Invalid refresh token
500	Token refresh failed

Token gating

Verify token access (POST)

POST /api/auth/token-gating/verify

Checks whether a wallet holds sufficient $RAVE tokens on Base mainnet.

Request body

Field	Type	Required	Description
`fid`	string	Yes	Farcaster ID
`address`	string	Yes	Ethereum address (0x-prefixed, 42 characters)

Response

{
  "fid": "12345",
  "address": "0x...",
  "hasAccess": true,
  "tokenGated": true,
  "minBalance": "1000000000000000000",
  "token": "RAVE",
  "chain": "base",
  "message": "User has sufficient $RAVE balance",
  "timestamp": "2026-03-19T00:00:00Z"
}

Errors

Code	Description
400	Missing fid or address, or invalid Ethereum address
500	Verification failed

Verify token access (GET)

GET /api/auth/token-gating/verify?address=0x...

Query parameters

Parameter	Type	Required	Description
`address`	string	Yes	Ethereum address (0x-prefixed, 42 characters)

Response

{
  "address": "0x...",
  "hasAccess": true,
  "tokenGated": true,
  "minBalance": "1000000000000000000",
  "token": "RAVE",
  "chain": "base",
  "contractAddress": "0x6EE72eEDEfBa8937Ec8c36dEd9B8c1ef9ca7A3db",
  "rpcEndpoint": "https://mainnet.base.org"
}

Webhook events

Event	Description
`user.created`	New user registered
`user.updated`	Profile updated
`user.deleted`	Account deleted

​Authentication API

​Auth middleware

​Request format

​JWT payload

​Error responses

​Sign up

​Request body

​Response

​Errors

​Sign in

​Request body

​OAuth sign in

​GitHub

​Google

​Wallet sign in (SIWE)

​How it works

​Request body

​Response

​Account linking

​Errors

​Get current user

​Response

​Errors

​Update profile

​Request body (POST)

​Errors (POST)

​Request body (PATCH)

​Change password

​Request body

​Response

​Errors

​Forgot password

​Request body

​Response

​Errors

​Reset password

​Request body

​Response

​Errors

​Farcaster authentication

​Verify Farcaster identity

​Request body

​Response

​Errors

​Refresh Farcaster token

​Request body

​Response

​Errors

​Token gating

​Verify token access (POST)

​Request body

​Response

​Errors

​Verify token access (GET)

​Query parameters

​Response

​Webhook events

Authentication API

Auth middleware

Request format

JWT payload

Error responses

Sign up

Request body

Response

Errors

Sign in

Request body

OAuth sign in

GitHub

Google

Wallet sign in (SIWE)

How it works

Request body

Response

Account linking

Errors

Get current user

Response

Errors

Update profile

Request body (POST)

Errors (POST)

Request body (PATCH)

Change password

Request body

Response

Errors

Forgot password

Request body

Response

Errors

Reset password

Request body

Response

Errors

Farcaster authentication

Verify Farcaster identity

Request body

Response

Errors

Refresh Farcaster token

Request body

Response

Errors

Token gating

Verify token access (POST)

Request body

Response

Errors

Verify token access (GET)

Query parameters

Response

Webhook events