Skip to main content
The K8s Scheduler API uses OAuth 2.0 for authentication with Google as the identity provider. After successful authentication, sessions are managed via secure HTTP cookies.

​
OAuth Flow

​
Initiate OAuth Login

GET /login
Initiates the OAuth 2.0 authorization flow by redirecting to Google’s authorization endpoint. Query Parameters:
​
redirect
string
Relative URL to redirect to after successful login (e.g., /invite?token=abc). Must start with / and not //.
Response: Redirects to Google OAuth consent screen with a state token stored in a secure cookie. Example: 
curl -X GET "https://your-domain.com/login?redirect=/dashboard" \
  -L

​
OAuth Callback

GET /oauth2/callback
Handles the OAuth callback from Google after user authorization. This endpoint:
  • Validates the state token
  • Exchanges the authorization code for an access token
  • Fetches user profile from Google
  • Creates or updates user account
  • Creates a session
  • Handles tier selection (if billing is enabled)
  • Handles invite flow (if redirect cookie present)
Query Parameters:
​
code
string
required
Authorization code from Google OAuth
​
state
string
required
State token for CSRF protection
Response: Redirects to:
  • /tier/select - If billing enabled and user hasn’t selected a tier
  • Invite page - If user was invited to a team
  • / - Dashboard for existing users
Example: 
# This is called automatically by Google OAuth
curl -X GET "https://your-domain.com/oauth2/callback?code=AUTH_CODE&state=STATE_TOKEN" \
  -L

​
Session Management

​
Logout

POST /logout
Ends the current user session by deleting the session from the database and clearing the session cookie. Authentication: Required (session cookie) Request Body: No body required. Query Parameters:
​
redirect
string
Relative URL to redirect to after logout (default: /)
Response: Redirects to the specified URL (or /) and clears the session cookie. Example: 
curl -X POST "https://your-domain.com/logout" \
  -H "Cookie: session=your-session-id" \
  -L

​
Session Details

Sessions are created after successful OAuth authentication and stored in the database with the following properties:
  • ID: Unique session identifier stored in HTTP-only cookie
  • UserID: Associated user ID
  • Email: User’s email address
  • Tier: User’s subscription tier (free, business, enterprise)
  • CurrentTeamID: Active team context for RBAC operations
  • IPAddress: Client IP address at session creation
  • UserAgent: Client user agent string
  • ExpiresAt: Session expiration timestamp
  • Name: session (configurable)
  • HttpOnly: true (prevents JavaScript access)
  • Secure: true in production
  • SameSite: Lax
  • Path: /
  • Domain: Configurable (supports subdomains)
  • MaxAge: Configurable (default varies by deployment)

​
Dev Mode Authentication

​
Dev Login (Development Only)

GET /dev/login
Bypass OAuth authentication in development mode. Only available when devMode: true in configuration. Query Parameters:
​
email
string
Email address for dev user (default: [email protected])
Response: Creates a session and redirects to dashboard. Example: 
curl -X GET "https://localhost:8080/dev/[email protected]" \
  -L
Dev mode authentication should never be enabled in production environments.

​
Registration Policies

The API supports three registration policies:
  1. Open - Anyone can register
  2. Allowed Domains - Only users with email addresses from configured domains can register
  3. Invite Only - Users can only register via team invitations
The registration policy is enforced during the OAuth callback. If a user is rejected due to policy, they receive a 403 Forbidden response.

​
First User Special Handling

The first user to authenticate receives special privileges:
  • Automatically assigned platform_admin role
  • Receives enterprise tier (when billing is disabled)
  • Creates the initial organization and team

​
Error Responses

All authentication endpoints may return the following errors:
​
error
string
Human-readable error message

​
Common Error Codes

  • 400 Bad Request - Invalid state token or missing authorization code
  • 403 Forbidden - Registration policy violation or email not verified
  • 500 Internal Server Error - Token exchange failed or database error

Build docs developers (and LLMs) love

Get started for freeTalk to us