All Forge API endpoints require authentication using session cookies provided by BetterAuth.
How It Works
Forge uses BetterAuth for authentication. When a user signs in through the web interface, a session cookie is created and automatically included in subsequent requests.
Session Cookie
The session is stored in a cookie that is:
- HttpOnly - Cannot be accessed by JavaScript
- Secure - Only transmitted over HTTPS in production
- SameSite - Protected against CSRF attacks
Making Authenticated Requests
When making API requests from:
Browser/Web Application:
fetch('/api/dashboards', {
method: 'GET',
credentials: 'include' // Include cookies
})
curl -X GET http://localhost:3000/api/dashboards \
-H "Cookie: session=your-session-token" \
-H "Content-Type: application/json"
import fetch from 'node-fetch';
const response = await fetch('http://localhost:3000/api/dashboards', {
headers: {
'Cookie': 'session=your-session-token',
'Content-Type': 'application/json'
}
});
Getting a Session Token
Web Application
In a web application, users authenticate through the BetterAuth login flow:
- User visits the login page
- Signs in with email/password or OAuth provider
- BetterAuth creates a session cookie automatically
- All subsequent API requests include the cookie
Programmatic Access
For server-to-server or script-based access, you’ll need to:
- Authenticate using BetterAuth’s API endpoints
- Extract the session cookie from the response
- Include it in subsequent requests
// Example: Login programmatically
const loginResponse = await fetch('http://localhost:3000/api/auth/sign-in', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
email: '[email protected]',
password: 'password123'
})
});
// Extract session cookie
const cookies = loginResponse.headers.get('set-cookie');
const sessionCookie = cookies.split(';')[0];
// Use in subsequent requests
const dashboardsResponse = await fetch('http://localhost:3000/api/dashboards', {
headers: {
'Cookie': sessionCookie
}
});
Session Verification
Every API endpoint verifies the session using:
const session = await auth.api.getSession({
headers: await headers()
});
if (!session) {
return new NextResponse("Unauthorized", { status: 401 });
}
session object contains:
{
user: {
id: string,
email: string,
name: string,
emailVerified: boolean,
image?: string
},
session: {
id: string,
token: string,
expiresAt: Date,
userId: string
}
}
Unauthorized Response
If authentication fails, the API returns:
HTTP/1.1 401 Unauthorized
Content-Type: text/plain
Unauthorized
Security Best Practices
Never expose session tokens in client-side code, logs, or error messages. Always use HTTPS in production.
- Store session cookies securely
- Use HTTPS in production to prevent token interception
- Implement proper session expiration and refresh mechanisms
- Never log or expose session tokens
- Validate sessions on every request
OAuth Providers
Forge supports authentication through:
- Google OAuth
- GitHub OAuth
- Notion OAuth
Connected accounts are managed through the Accounts API.