> ## Documentation Index
> Fetch the complete documentation index at: https://raveculture-mintlify-api-provision-docs-1774045983.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication API

> Authentication API endpoints for user management and identity verification

# 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

```bash theme={null}
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                 |

<Note>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](/security#row-level-security) for details.</Note>

## Sign up

```http theme={null}
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

```json theme={null}
{
  "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                                                                               |

## Sign in

```http theme={null}
POST /api/auth/callback/credentials
```

### Request body

```json theme={null}
{
  "email": "user@example.com",
  "password": "securepassword"
}
```

## OAuth sign in

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

```http theme={null}
GET /api/auth/github
```

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

### Google

```http theme={null}
GET /api/auth/google
```

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

## Wallet sign in (SIWE)

```http theme={null}
POST /api/auth/callback/wallet
```

Sign in using an Ethereum wallet via [Sign-In with Ethereum (SIWE)](https://eips.ethereum.org/EIPS/eip-4361). This flow is designed for Base smart wallets and supports ERC-6492 signature verification for pre-deployed wallets.

### How it works

1. The client opens the Base Account SDK popup and requests a SIWE signature on Base Mainnet (chain ID `0x2105`).
2. The signed SIWE message and signature are sent to the `wallet` NextAuth credentials provider.
3. The server parses the SIWE message, validates the domain, and verifies the signature.
4. If no account exists for the wallet address, a new user is created automatically.
5. 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 |

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

## Get current user

```http theme={null}
GET /api/settings
```

Requires session authentication. Returns the current user profile.

### Response

```json theme={null}
{
  "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`.

```http theme={null}
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 |

```http theme={null}
PATCH /api/settings
```

### Request body (PATCH)

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

## Change password

```http theme={null}
POST /api/settings/password
```

### Request body

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

### Response

```json theme={null}
{
  "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

```http theme={null}
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

```json theme={null}
{
  "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

```http theme={null}
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

```json theme={null}
{
  "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

```http theme={null}
POST /api/auth/farcaster/verify
```

```http theme={null}
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

```json theme={null}
{
  "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

```http theme={null}
POST /api/auth/farcaster/refresh
```

```http theme={null}
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

```json theme={null}
{
  "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)

```http theme={null}
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

```json theme={null}
{
  "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)

```http theme={null}
GET /api/auth/token-gating/verify?address=0x...
```

#### Query parameters

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

#### Response

```json theme={null}
{
  "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     |