Skip to main content

Authentication Overview

This guide provides technical details about authentication implementation in Deepdesk.

Authentication Methods​

Deepdesk supports multiple authentication methods:

  • SSO (Single Sign-On) - OAuth2 authorization code flow for platform integration
  • Magic Link - Email-based temporary tokens for dashboard access
  • API Key - Fallback method when SSO and magic links aren't possible
  • JWT - Token-based authentication with shared secrets

Login Flow​

The following diagram illustrates the complete authentication flow in Deepdesk, including SSO, Magic Link, and access request workflows:

This flow shows how Deepdesk handles different authentication scenarios:

  1. Existing Users: If the user is already logged in, the SDK loads immediately
  2. SSO Path: When the platform supports SSO, users authenticate through the OAuth2 flow
  3. Magic Link Path: For platforms without SSO, users receive a magic link via email
  4. Access Requests: New users go through an approval workflow before receiving their magic link (Magic Link only; see below)
  • The agent is logged into the CX platform and sees an overlay above the input field with a button "Sign in to Deepdesk".
  • When the agent opens this link, if the email address does not exist yet, an access request email is sent to that address.
  • The agent opens the link in the email; a request is sent to the manager.
  • The manager approves the request, and a magic link is sent to the agent.
  • The agent opens the magic link and is logged in to Deepdesk.
  • The agent returns to the CX platform, refreshes, and sees Deepdesk suggestions.
Implementation

Magic link implementation (GitHub)

SSO flow (step-by-step)​

  • The agent is logged into the CX platform and sees an overlay above the input field with a button "Sign in to Deepdesk".
  • When the agent opens this link, the OAuth2 flow is performed with the platform.
  • When the flow is successful, the user is logged in to Deepdesk. New users are created automatically (see User Management for trial mode and role-based access).
  • The agent returns to the CX platform, refreshes, and sees Deepdesk suggestions.
SSO and access requests

Access requests are not used for SSO. Authenticated SSO users are always logged in; new users are created automatically when they authenticate. To control which SSO users can access Deepdesk, use role-based IAM or trial mode.

Implementation

Platform SSO implementation (GitHub)

Documentation​

SSO​

Go to SSO documentation

Learn about the OAuth2 authorization code flow implementation for Single Sign-On:

  • OAuth2 authorization code flow specification
  • Platform SSO sequence diagram
  • Step-by-step authentication process
  • End-to-end login flow from agent perspective
  • OAuth2 Roles - Automatic role assignment using OIDC

Go to Magic Link documentation

Learn about passwordless authentication using email-based magic links:

  • Email-based temporary token authentication
  • Access request and approval workflow
  • Login flow diagram
  • Security considerations
  • Implementation details

API Key​

Go to API Key documentation

Learn about API key authentication for platforms without OAuth2 support:

  • Widget-based authentication flow
  • Security considerations and risks
  • Secret management
  • Current platform usage (LiveEngage, Genesys WDE)

JWT session (cookies)​

Go to JWT session documentation

Learn about how the Backend uses JWT for session authentication after login:

  • Access and refresh token cookies
  • Cookie attributes (HttpOnly, Secure, SameSite)
  • /auth/refresh and token lifecycle

Platform JWT (shared secret): Shared Secret JWT (Tracebuzz) — When the platform generates a JWT and the SDK exchanges it for session cookies.

Outbound links (e.g. Genesys WDE): Exchange tokens (Genesys WDE) — Short-lived tokens for personal collection and other links opened outside the app context.

Permissions System​

Go to Permissions System documentation

Learn about the technical implementation of Deepdesk's permissions system:

  • Django permissions and content types architecture
  • Group-based access control
  • Provisioning and deployment
  • Permission enforcement in API views
  • Test data factories for access control testing

Staff SSO​

Go to Staff SSO documentation

Learn about how Deepdesk staff members authenticate to tenant admin dashboards:

  • Google Workspace integration via Onboarding Service
  • OAuth2/OIDC flow architecture
  • Onboarding Service as identity provider
  • User provisioning and group assignment
  • Customer Success staff access