SSO Callback URL Reference

Complete guide to all supported callback URL patterns for RegardingWork SSO integration

🚨 WRONG SSO INITIATION DETECTED

Important: Some apps are using /mini-app-sso which doesn't exist!

❌ WRONG: https://hub.regardingwork.com/mini-app-sso
✅ CORRECT: https://hub.regardingwork.com/api/auth/sso/authorize

Fix needed: Use the proper SSO initiation flow documented in our SSO Integration Guide

✅ ALL CALLBACK PATTERNS SUPPORTED

Good news! Once you initiate SSO correctly, your callback URL will work regardless of which pattern you use. We support all legacy and modern callback URL formats for maximum compatibility.

No Migration Needed: Existing callback implementations continue to work without changes.

Supported Callback Routes

All these callback URL patterns are supported and return identical JSON responses:

API-Style Callback

/api/auth/sso/callback

Best for: Apps using API-first architecture

Used by: CE, Desk, many legacy integrations

Example:
https://ce.regardingwork.com/api/auth/sso/callback

Auth Callback

/auth/sso/callback

Best for: Traditional authentication flows

Used by: Legacy apps, documentation examples

Example:
https://yourapp.com/auth/sso/callback

Simple Callback

/sso/callback

Best for: New mini-apps, clean URLs

Used by: New integrations, testing apps

Example:
https://testingparty.regardingwork.com/sso/callback

Universal Support

✅ ALL PATTERNS

Result: Same JSON response from all routes

No matter which pattern you use, you get identical functionality

Guarantee:
Backward compatibility forever

Callback Response Format

All callback routes return the same JSON response format:

✅ Success Response

{
  "success": true,
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "user_id": "29",
  "username": "michelini",
  "message": "SSO authentication successful"
}

❌ Error Response

{
  "error": "No token received from SSO"
}

Common errors: Missing token, invalid token, user not found

How to Choose Your Callback URL

New Apps

Use the simple pattern:

/sso/callback

Clean, modern, easy to remember

API Apps

Use the API pattern:

/api/auth/sso/callback

Follows REST API conventions

Legacy Apps

Keep existing pattern:

/auth/sso/callback

No migration needed

URL Parameters Received

When the Hub redirects back to your callback URL, these parameters are included:

Parameter	Description	Example	Required
`token`	JWT authentication token	`eyJhbGciOiJIUzI1NiI...`	Yes
`access_token`	Alternative name for token (backward compatibility)	`eyJhbGciOiJIUzI1NiI...`	Optional
`user_id`	Numeric user identifier	`29`	Yes
`username`	User's display name	`michelini`	Yes

Note: Both token and access_token parameters are provided for maximum compatibility. Your app can check for either one.

Testing Your Callback

To test if your callback URL is working correctly:

1. Manual Test

Use the correct SSO initiation URL (replace with your domain):

https://hub.regardingwork.com/api/auth/sso/authorize?redirect_uri=https%3A%2F%2Fyour-domain.com%2Fsso%2Fcallback&service=yourapp

2. Direct Test

Test your endpoint directly:

curl "https://your-domain.com/sso/callback?token=test"

Should return: {"error":"Token validation failed"}

Troubleshooting

Common Issues

404 Error: Route not implemented
CORS Error: Domain not whitelisted
Infinite Loop: Callback redirects back to SSO
No Token: URL parameters not received

Solutions

404: Implement any of the three supported routes
CORS: Request domain addition via support
Loop: Check callback doesn't redirect to login
Token: Verify URL parameter parsing

Still having issues? Check our SSO troubleshooting guide or contact support with your specific callback URL pattern.

Quick Reference

✅ Supported Routes

/api/auth/sso/callback
/auth/sso/callback
/sso/callback

📄 Response

JSON format
Includes token & user data
Same across all routes

🔧 Parameters

token
user_id
username

🛡️ Compatibility

All patterns supported
Backward compatible
Future-proof

Back to Documentation SSO Integration Guide