OAuth Flow

Copy this flow exactly for a reliable 2-minute integration. Most integration failures come from small deviations in start URL, redirect URI, or token exchange.

Use Exactly These Endpoints

Use your LoginSign deployment base URL (for example https://loginsign.com). When you self-host, replace the host with your own origin everywhere below.

Quickstart (Copy/Paste)

1. Start login only via /oauth/authorize.
2. Receive ?code=...&state=... at your callback URL.
3. Exchange code on your backend via POST /oauth/token.
4. Use access token to fetch /api/user.

1) Authorization Request (Frontend Redirect)

Recommended scope for documentation and new integrations: openid email profile (single string, space-separated). LoginSign forwards scope through the flow; use the same convention everywhere you copy examples.

GET https://loginsign.com/oauth/authorize?
  client_id=YOUR_CLIENT_ID&
  redirect_uri=https://yourapp.com/callback&
  response_type=code&
  scope=openid%20email%20profile&
  state=random_state_string

Do not start with /login or /api/auth/*. Always start with /oauth/authorize.

2) Token Exchange (Backend)

Exchange the received code on your server. The redirect_uri must be exactly the same value you used in step 1.

POST https://loginsign.com/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&
code=AUTHORIZATION_CODE&
client_id=YOUR_CLIENT_ID&
client_secret=YOUR_CLIENT_SECRET&
redirect_uri=https://yourapp.com/callback

Recommended ENV Setup

Don't hardcode OAuth values in frontend code. Keep environment values for local and production.

# Frontend (.env.local)
LOGINSIGN_CLIENT_ID=YOUR_CLIENT_ID
LOGINSIGN_REDIRECT_URI=http://localhost:3000/oauth/loginsign/callback

# Backend (.env)
LOGINSIGN_CLIENT_ID=YOUR_CLIENT_ID
LOGINSIGN_CLIENT_SECRET=YOUR_CLIENT_SECRET
LOGINSIGN_REDIRECT_URI=http://localhost:3000/oauth/loginsign/callback

Redirect URIs

The Redirect URI is the URL in your app to which LoginSign sends the user after they allow or deny access. You must register one or more Redirect URIs in the Developer Portal when creating or editing your application.

• Match rule: Use the same redirect_uri value in authorize + token exchange. Keep it byte-identical to avoid edge-case failures.
• HTTPS in production: Use https:// for production. http://localhost is allowed for local development.
• Callback path: Typically something like https://yourapp.com/oauth/callback or https://yourapp.com/auth/callback. Your app must handle this route: read the code and state query parameters, exchange the code for a token, and verify state.

Add all Redirect URIs that your app will use (e.g. production and staging). You can add or remove URIs later in the application settings.

Quick Validation

Validate your setup before go-live and after each redirect URI change:

GET https://loginsign.com/api/oauth/healthcheck?
  client_id=YOUR_CLIENT_ID&
  redirect_uri=https://yourapp.com/oauth/loginsign/callback

You can also run this check directly inside the Developer Portal under Settings → Redirect URIs → OAuth config check.

Troubleshooting (Symptom → Fix)

• Redirect URI not allowed: Add exact callback URL in Developer Portal and run OAuth config check.
• Lands on LoginSign dashboard: Ensure your app starts with /oauth/authorize, not /login.
• Consent fails / “valid email required”: The signing-in user needs a valid primary email on their LoginSign profile before a new app connection can be created.
• invalid_client: Check client ID/secret pair and environment mix-ups (staging vs production).
• invalid_grant: Code expired, already used, or redirect_uri mismatch in token exchange.
• Sign-in failed in callback: Log the raw response from /oauth/token (status + JSON) before generic UI errors.