Skip to main content

​
Feature Guide: GCX Authentication Integration

​
1. Overview

GCX Authentication Integration connects your Fiftyknots account with external systems using secure, industry-standard OAuth 2.0 flows. This feature lets you authenticate once and seamlessly access integrated platforms without managing multiple credentials. You maintain control over which systems can access your data while building faster with pre-authenticated connections to tools you already use.

​
2. Step-by-Step Guide

  1. Navigate to authentication settings - From any authenticated page in Fiftyknots, access your account settings. The system maintains your session state across all platform pages including the dashboard, workspace, and analytics views.
  2. Initiate OAuth connection - Click “Connect External System” to begin the OAuth flow. The platform generates a secure authorization code specific to your session using POST /api/v1/auth/generate-auth-code.
  3. Authorize the connection - You’ll be redirected to the external system’s login page. Sign in with your credentials there. The external system validates your identity and redirects you back to Fiftyknots with a temporary auth code.
  4. Exchange authorization code - Fiftyknots automatically exchanges the temporary code for an access token via POST /api/v1/auth/exchange-auth-code. This happens in the background - you’ll see a confirmation screen when complete.
  5. Verify active session - Return to your dashboard. The platform confirms your authenticated state through GET /api/v1/auth/session. Your connected systems now appear in your account settings with active status indicators.
  6. Access integrated features - Navigate to features that leverage the external connection. The authentication persists across sessions until you explicitly revoke it or log out using POST /api/v1/auth/logout.

​
3. Common Questions

Q: Do I need to re-authenticate every time I use an integrated feature?
A: No. Once you complete the OAuth flow, the platform maintains your session. You can check active sessions at any time via GET /api/v1/auth/sessions and the connection persists until you revoke it or your session expires. Q: Can I revoke access to specific external systems?
A: Yes. Navigate to your account settings and view all active sessions. Each connected system displays with a session ID. Use DELETE /api/v1/auth/sessions/:sessionId to revoke access to any specific integration without affecting your other connections. Q: What happens if my authentication fails or expires?
A: The platform detects expired sessions automatically. You’ll see a prompt to re-authenticate when you attempt to use a feature requiring that connection. Your work in progress remains saved - you simply need to reconnect and continue. Q: Is my authentication information shared with other Fiftyknots users?
A: No. Each authentication session is unique to your user account. Even if you collaborate on team projects, your external system credentials remain private. Other users must authenticate separately with their own credentials. Q: Can I use SSO with my existing corporate identity provider?
A: Yes. Fiftyknots supports Single Sign-On through POST /api/v1/auth/sso. This allows you to use your organization’s identity system to authenticate, applying your company’s security policies while accessing the platform.

​
4. Troubleshooting

Issue: Authorization redirect fails or returns an error
Solution: Clear your browser cache and cookies, then restart the OAuth flow from step 1. If the error persists, verify that you’re using a supported browser and that third-party cookies are enabled. Check that the external system you’re connecting to is currently operational. Issue: Session expires unexpectedly during active use
Solution: Check your active sessions using GET /api/v1/auth/sessions. Session timeouts occur for security reasons after extended inactivity. Re-authenticate using the same OAuth flow. To maintain longer sessions, ensure you’re actively using the platform and that your browser isn’t blocking session cookies. Issue: Cannot revoke a specific session or see orphaned sessions
Solution: Navigate to your account settings and review all sessions displayed by the sessions endpoint. Each session shows when it was created and last used. Delete individual sessions using their unique session ID. If you see sessions you don’t recognize, revoke them immediately and verify your account security. Issue: External system shows “already connected” but Fiftyknots doesn’t recognize the connection
Solution: The external system may have cached your previous authorization. Log into the external system directly and revoke Fiftyknots’ access from their connected apps settings. Then restart the OAuth flow from Fiftyknots. This clears both sides and establishes a fresh connection. Session Management - View and control all active authentication sessions across devices and platforms. This feature works directly with GCX Authentication to give you visibility into where and when you’re logged in, with one-click revocation for any session. Developer Dashboard - If you’re building integrations or custom playbooks, the Developer Dashboard uses the same OAuth infrastructure. You can generate API keys and manage developer-specific authentication credentials that extend the core GCX Authentication system. Team Project Access - When working on collaborative ventures, GCX Authentication ensures each team member authenticates independently while sharing project resources. Your authentication determines which projects you can access and what actions you can perform within them.