Get Login Options

The Login Options API provides information about what authentication methods are available for a project. This allows the frontend to dynamically adapt its UI based on backend configuration, rather than hardcoding which login methods to display.

Overview

Before rendering the login page, the application queries this endpoint to determine:

Which grant types are enabled (password, social login, OIDC, etc.)
Which SSO providers are configured
Whether OIDC is available

This creates a backend-driven configuration pattern where the authentication UI adapts automatically to what the backend permits.

Endpoint

GET /idp/v1/Authentication/GetLoginOptions

Request Headers

Header	Required	Description
`X-Blocks-Key`	Yes	Project API key for identification
`Content-Type`	Yes	Must be `application/json`

Example Request

GET /idp/v1/Authentication/GetLoginOptions HTTP/1.1
Host: api.seliseblocks.com
X-Blocks-Key: D370734d712a245b4a77fd887cfa89f34
Content-Type: application/json

Example Response

{
  "allowedGrantTypes": [
    "password",
    "client_credential",
    "social",
    "switch_organization"
  ],
  "ssoInfo": [
    {
      "provider": "google",
      "audience": "https://<deployed-domain>/login"
    }
  ]
}

Response Schema

allowedGrantTypes

Array of strings indicating which authentication flows are permitted:

Value	Description
`password`	Email/password authentication
`social`	SSO via OAuth providers (Google, GitHub, etc.)
`client_credential`	Machine-to-machine authentication
`switch_organization`	Organization context switching

ssoInfo

Array of configured SSO providers. Each entry contains:

Field	Type	Description
`provider`	string	Provider identifier (e.g., `google`, `github`, `microsoft`)
`audience`	string	Audience set for the SSO provider. Note: Redirect URL and Audience are set from Blocks Cloud.

Authentication Considerations

This endpoint does not require authentication. It is designed to be called:

Before a user is logged in
On the login page itself
To determine which UI elements to render

This is intentional—it allows the frontend to adapt without requiring a session.

Data Freshness

Why Fresh Data Matters

An administrator enables or disables SSO providers
New OAuth applications are configured
Project settings are modified in the admin dashboard
Security policies are updated

Since users might log out and back in after such changes, the application should fetch fresh login options rather than relying on stale cached data.

Recommended Behavior

Fetch on page load - Always retrieve current options when the login page loads
Refresh periodically - Poll periodically (e.g., every 30 seconds) to detect configuration changes
Refresh on visibility change - When the user returns to the login page after switching tabs, refetch to catch any changes made while away
Handle stale data gracefully - If a fetch fails, continue showing the last known options rather than hiding login methods entirely

Error Handling

HTTP Status Codes

Status	Meaning	Recommended Action
200	Success	Process response and render UI
403, 404, 406, 424	Project misconfiguration	Display "Incorrect Project Key" message
5xx	Server error	Display "Service Temporarily Unavailable" message
Network error	Connectivity issue	Retry with exponential backoff

Handling Different Error Types

Configuration Errors (4xx except 401): These typically indicate the project is not properly set up. Display a clear error message directing users to check their configuration.

Server Errors (5xx): These indicate temporary issues. Allow retry and consider showing cached login options if available.

Network Errors: Implement retry logic with backoff to handle transient connectivity issues.

Conditional UI Rendering

The application should only display login methods that are both:

Present in allowedGrantTypes
Properly configured (e.g., SSO providers must exist in ssoInfo)

Rendering Rules

Condition	UI Element
`password` in allowedGrantTypes	Show email/password form
`social` in allowedGrantTypes AND ssoInfo.length > 0	Show SSO buttons
`authorization_code` in allowedGrantTypes	Show OIDC button

Example Flow

1. Fetch login options
2. Check if "password" is in allowedGrantTypes
   → If yes, render email/password form
3. Check if "social" is in allowedGrantTypes AND ssoInfo has entries
   → If yes, render SSO provider buttons
   → For each provider in ssoInfo, render its button
4. Check if "authorization_code" is in allowedGrantTypes
   → If yes, render OIDC button

SSO Provider Mapping

When rendering social login buttons, map the provider names to their corresponding UI:

Provider Value	UI Label	Icon
`google`	Google	Google icon
`github`	GitHub	GitHub icon
`microsoft`	Microsoft	Microsoft icon
`linkedin`	LinkedIn	LinkedIn icon
`x`	X (Twitter)	X icon

Only render buttons for providers that appear in the ssoInfo array. If ssoInfo is empty, do not render any social login buttons even if "social" is in allowedGrantTypes.

Periodic Refresh Strategy

Why Poll?

Even though login page sessions are typically short, polling ensures:

The UI reflects the latest backend configuration
If an admin disables a provider mid-session, it will be reflected on next visibility change
Users who keep the login page open receive updates

Polling Best Practices

Interval: 30 seconds is a reasonable default—frequent enough to catch changes, not so often as to strain the server
When to poll:
- Only when the tab is visible (refetchIntervalInBackground: false)
- On page focus (when user returns to the tab)
- On initial page load
When to stop polling:
- When the user navigates away from the login page
- When the component unmounts
Graceful degradation:
- If polling fails, continue showing cached options
- Log errors but don't disrupt the user experience

Security Considerations

Information Exposure

This endpoint intentionally exposes:

Which login methods are enabled (safe to publicize)
Which SSO providers are configured (generally safe)
OAuth redirect URLs (necessary for the flow)

This endpoint does not expose:

User accounts or credentials
Session tokens
Backend system details beyond what's necessary

No Authentication Required

By design, this endpoint works without authentication. This allows:

Displaying appropriate login options to unauthenticated users
Pre-determining available methods before establishing a session
Graceful fallback if all authentication methods are disabled

Caching Recommendations

Always Consider Data Stale (staleTime: 0)

Login options should never be cached as fresh data. Always set the equivalent of staleTime: 0—meaning data is considered stale immediately after fetching.

Why always stale?

Administrators can change login options at any time
Security policies might require disabling methods immediately
New SSO providers can be added without warning
A user who logged out might have had their access changed

Cache Invalidation Triggers

Data should be considered stale and refetched when:

Immediately after fetching (no grace period)
User returns to the page
User switches browser tabs and returns
Any visibility change event occurs
Polling interval triggers

Caching Behavior

If implementing client-side caching:

Do not treat data as fresh - always refetch on relevant triggers
Show cached/stale data while refetching - prevents UI flash
Background refresh - fetch fresh data without blocking UI

Why Not Even 5 Minutes?

Even a 5-minute cache is inappropriate because:

Administrators may change login options at any moment
A user might log out, have their tokens expire, then attempt to log back in within minutes
Security-sensitive configurations should reflect changes immediately

Example User Flows

User visits /login
→ Fetch GetLoginOptions
→ Response: allowedGrantTypes = ["password"]
→ Render only email/password form
User enters credentials
→ POST /Token (grant_type=password)
→ Success, redirect to app

Flow 2: SSO with Password Fallback

User visits /login
→ Fetch GetLoginOptions
→ Response: allowedGrantTypes = ["password", "social"], ssoInfo = [{provider: "google"}]
→ Render email/password form + Google button
User clicks "Sign in with Google"
→ GET /GetSocialLogInEndPoint
→ Redirect to Google
→ User authenticates with Google
→ Google redirects back with code
→ POST /Token (grant_type=social)
→ Success, redirect to app

Flow 3: Multiple SSO Providers

User visits /login
→ Fetch GetLoginOptions
→ Response: allowedGrantTypes = ["social"], ssoInfo = [{provider: "google"}, {provider: "github"}]
→ Render Google button + GitHub button (no password form)
User clicks GitHub
→ GET /GetSocialLogInEndPoint
→ Redirect to GitHub
→ User authenticates
→ POST /Token (grant_type=social)
→ Success

Summary

Aspect	Recommendation
Fetch on page load	Always
Stale time	0 (always considered stale)
Polling interval	~30 seconds
Refresh on tab focus	Yes
Cache as fresh	Never
Error handling	Show cached data, log error
Authentication required	No

Discover Login Options​

Overview​

Endpoint​

Request Headers​

Example Request​

Example Response​

Response Schema​

Authentication Considerations​

Data Freshness​

Why Fresh Data Matters​

Recommended Behavior​

Error Handling​

HTTP Status Codes​

Handling Different Error Types​

Conditional UI Rendering​

Rendering Rules​

Example Flow​

SSO Provider Mapping​

Periodic Refresh Strategy​

Why Poll?​

Polling Best Practices​

Security Considerations​

Information Exposure​

No Authentication Required​

Caching Recommendations​

Always Consider Data Stale (staleTime: 0)​

Cache Invalidation Triggers​

Caching Behavior​

Why Not Even 5 Minutes?​

Example User Flows​

Flow 1: Password Login Only​

Flow 2: SSO with Password Fallback​

Flow 3: Multiple SSO Providers​

Summary​

Discover Login Options