Login Endpoints

Login endpoints initiate the OAuth 2.0 authorization code flow by redirecting users to the provider’s authorization page.

Common Flow

All login endpoints follow this pattern:

Generate a random state token (32-character hex string)
Resolve the application origin URL
Build provider-specific authorization URL
Set security cookies (state, origin, redirect_uri, flow)
Redirect user to provider’s authorization page

Shared Query Parameters

flow

string

default:"login"

Authentication flow type:

login - Standard login flow (default)
bind - Account binding flow to link provider to existing user

Initiates SecondMe OAuth flow for primary authentication.

Implementation Details

Source: src/app/api/auth/login/route.ts:11-60 Authorization URL: https://go.second.me/oauth/ Redirect URI: {appOrigin}/api/auth/callback Scopes: Configured in src/lib/secondme.ts:10

user.info
user.info.shades
user.info.softmemory
chat
note.add
voice

Request

cURL
JavaScript
HTML

# Standard login
curl -X GET "https://your-app.com/api/auth/login" \
  -L

# Account binding
curl -X GET "https://your-app.com/api/auth/login?flow=bind" \
  -L

// Standard login
window.location.href = '/api/auth/login';

// Account binding
window.location.href = '/api/auth/login?flow=bind';

<!-- Standard login -->
<a href="/api/auth/login">Login with SecondMe</a>

<!-- Account binding -->
<a href="/api/auth/login?flow=bind">Link SecondMe Account</a>

Response

Redirects to SecondMe authorization page with parameters:

client_id

string

required

From SECONDME_CLIENT_ID environment variable

redirect_uri

string

required

Callback URL: {appOrigin}/api/auth/callback

response_type

string

required

Always code (authorization code flow)

state

string

required

CSRF protection token (32-character hex)

Cookies Set

secondme_oauth_state

string

State token for validation (httpOnly, 10min expiry)

secondme_oauth_origin

string

Application origin URL (httpOnly, 10min expiry)

secondme_oauth_redirect_uri

string

Callback redirect URI (httpOnly, 10min expiry)

Flow type: login or bind (httpOnly, 10min expiry)

Initiates GitHub OAuth flow for developer authentication.

Implementation Details

Source: src/app/api/auth/login/github/route.ts:11-25 Authorization URL: https://github.com/login/oauth/authorize Redirect URI: {appOrigin}/api/auth/callback/github Scopes: read:user user:email Helper: buildGitHubAuthUrl() in src/lib/oauth.ts:22-31

Request

cURL
JavaScript
HTML

# Standard login
curl -X GET "https://your-app.com/api/auth/login/github" \
  -L

# Account binding
curl -X GET "https://your-app.com/api/auth/login/github?flow=bind" \
  -L

// Standard login
window.location.href = '/api/auth/login/github';

// Account binding
window.location.href = '/api/auth/login/github?flow=bind';

<!-- Standard login -->
<a href="/api/auth/login/github">
  <img src="/github-logo.svg" alt="Login with GitHub" />
</a>

<!-- Account binding -->
<button onclick="window.location.href='/api/auth/login/github?flow=bind'">
  Link GitHub Account
</button>

Response

Redirects to GitHub authorization page with parameters:

client_id

string

required

From GITHUB_ID environment variable

redirect_uri

string

required

Callback URL: {appOrigin}/api/auth/callback/github

scope

string

required

read:user user:email

state

string

required

CSRF protection token (32-character hex)

Cookies Set

github_oauth_state

string

State token for validation (httpOnly, 10min expiry)

github_oauth_origin

string

Application origin URL (httpOnly, 10min expiry)

github_oauth_redirect_uri

string

Callback redirect URI (httpOnly, 10min expiry)

Flow type: login or bind (httpOnly, 10min expiry)

Initiates Google OAuth flow for mainstream authentication.

Implementation Details

Source: src/app/api/auth/login/google/route.ts:11-25 Authorization URL: https://accounts.google.com/o/oauth2/v2/auth Redirect URI: {appOrigin}/api/auth/callback/google Scopes: openid profile email Additional Parameters:

access_type: offline - Requests refresh token
prompt: consent - Forces consent screen

Helper: buildGoogleAuthUrl() in src/lib/oauth.ts:100-112

Request

cURL
JavaScript
HTML

# Standard login
curl -X GET "https://your-app.com/api/auth/login/google" \
  -L

# Account binding
curl -X GET "https://your-app.com/api/auth/login/google?flow=bind" \
  -L

// Standard login
window.location.href = '/api/auth/login/google';

// Account binding
window.location.href = '/api/auth/login/google?flow=bind';

<!-- Standard login -->
<a href="/api/auth/login/google" class="google-signin-btn">
  Sign in with Google
</a>

<!-- Account binding -->
<a href="/api/auth/login/google?flow=bind">
  Link Google Account
</a>

Response

Redirects to Google authorization page with parameters:

client_id

string

required

From GOOGLE_CLIENT_ID environment variable

redirect_uri

string

required

Callback URL: {appOrigin}/api/auth/callback/google

response_type

string

required

Always code (authorization code flow)

scope

string

required

openid profile email

access_type

string

required

offline - Requests refresh token

prompt

string

required

consent - Forces consent screen for refresh token

state

string

required

CSRF protection token (32-character hex)

Cookies Set

google_oauth_state

string

State token for validation (httpOnly, 10min expiry)

google_oauth_origin

string

Application origin URL (httpOnly, 10min expiry)

google_oauth_redirect_uri

string

Callback redirect URI (httpOnly, 10min expiry)

Flow type: login or bind (httpOnly, 10min expiry)

Security Considerations

State Token ValidationThe state parameter is critical for CSRF protection. Never skip state validation in callback handlers.

Cookie SecurityAll cookies are set with:

httpOnly: true - Prevents XSS attacks
sameSite: 'lax' - CSRF protection
secure: true - HTTPS only (production)
maxAge: 600 - 10 minute expiration

Origin ResolutionThe resolveAuthOrigin() function (from src/lib/auth-origin.ts) determines the correct application origin for dynamic environments (development, staging, production).

Next Steps

Callback Handling

Learn how OAuth callbacks are processed after user authorization

Agent API

Authentication

User API

Debate API

Common Flow

Shared Query Parameters

Implementation Details

Request

Response

Cookies Set

Implementation Details

Request

Response

Cookies Set

Implementation Details

Request

Response

Cookies Set

Security Considerations

Next Steps

Callback Handling

Build docs developers (and LLMs) love

Agent API

Authentication

User API

Debate API

​Common Flow

​Shared Query Parameters

​SecondMe Login

​Implementation Details

​Request

​Response

​Cookies Set

​GitHub Login

​Implementation Details

​Request

​Response

​Cookies Set

​Google Login

​Implementation Details

​Request

​Response

​Cookies Set

​Security Considerations

​Next Steps

Callback Handling

Build docs developers (and LLMs) love

Common Flow

Shared Query Parameters

SecondMe Login

Implementation Details

Request

Response

Cookies Set

GitHub Login

Implementation Details

Request

Response

Cookies Set

Google Login

Implementation Details

Request

Response

Cookies Set

Security Considerations

Next Steps