DEV Community: Descope

Build Secure Multi-Agent Systems With CrewAI and Descope

Mrunank Pawar — Wed, 06 May 2026 15:00:00 +0000

This blog was originally published on Descope.

A single AI agent can summarize, analyze, or plan, but it struggles to scale across domains, maintain context, or specialize deeply enough for complex enterprise use cases. Multi-agent systems address these gaps by distributing responsibility across many specialized agents. Instead of asking one model to do everything, individual agents receive a defined role and scope. Each agent executes its part before results are stitched together. This avoids overload, reduces errors, and produces better outcomes than a single agent working alone.

Case in point: The CrewAI multi-agent platform structures multi-agent systems much like real-world teams. This design keeps workflows clear, predictable, and scalable while exposing the practical challenge of managing identity and access. But once you've got agents interacting, you need to think about safe and reliable orchestration: authentication, identity, permissions, and secure communication.

Enter the Descope Agentic Identity Hub, which helps you manage identity and access control for all agents in such a multi-agent system. Each agent can be managed and assigned the relevant permissions to perform exactly the tasks they are designed for and nothing more. Let's put this in practice!

Implementing Descope for a CrewAI Application

To make this concrete, there's a working example that ties everything together. You can follow the steps in this tutorial, or check out the finished sample app to see the complete implementation in action.

Here's what we'll be implementing:

A CrewAI crew with two different agents corresponding to two independent tasks: Calendar and Contacts
Descope Outbound apps for each API with defined OAuth scopes. Each agent will have its own scope and will only be able to perform actions based on these scopes.
User consent flows for granular permissioning
Backend session validation and secure token exchange
A unified output from the crew that combines results from both agents

Watch the video below or carry on reading!

Prerequisites

You'll need the following tools:

A Descope account: If you don't already have one, you can sign up for a Free Forever account.
Google Cloud APIs: Calendar and People/Contacts APIs
CrewAI: Python framework for multi-agent workflows
Python HTTP library: For API requests (requests, http, etc.)
A simple React frontend to connect the backend to

Configure Google OAuth credentials

For using google contact and calendar APIs, you need to set up google OAuth credentials.

Create OAuth credentials in the Google Cloud Console for the APIs your agents will access.
Go to your Google Cloud Console > APIs & Services > Credentials.
Create a new OAuth Client ID for each service: one for Calendar, one for Contacts.
Copy the Client ID and Client Secret for each app.
Add Authorized redirect URIs pointing back to your Descope Outbound app configuration.

Add Outbound Apps in Descope

Next, configure the outbound apps inside Descope so that each agent can request access tokens for its task. In the Descope Console, go to Outbound Apps.

Add Google Calendar and Google Contacts as new apps.
Paste the Client ID and Client Secret from Google for each app.
Set the redirect URIs to match the Google configuration.

The Descope docs provide more detailed instructions on how to set up outbound applications. While setting up outbound applications, pay attention to scopes. Scopes determine exactly what each agent can access. Configuring scopes in Descope rather than in code makes it easy to audit and update them later.

For this tutorial, we need two sets of scopes:

Calendar app: https://www.googleapis.com/auth/calendar.readonly and https://www.googleapis.com/auth/calendar (so the calendar agent can read existing events and create new ones)

Contacts app: https://www.googleapis.com/auth/contacts.readonly (so the contacts agent can look up user contacts but not modify them)

Keeping scopes granular ensures each task is limited to its responsibilities and prevents over-permissioning.

Configure Descope Inbound Application

Configure an Inbound App in your Descope console. The inbound app protects the front end and also uses the consent flow so that the user can grant consent. The token granted by inbound applications is used by the application backend to securely exchange and fetch outbound app tokens:

Descope already has a template flow that can be used for inbound applications. Start with that and customize as follows:

Insert a consent screen showing requested scopes for Calendar and Contacts.
Consent is stored for auditability and future requests.
Add two Outbound App Connection actions, one for each app. These are required to connect google calendar and contacts during the user login process.

Frontend authentication

When a user signs in through the inbound app, they're guided through the customized Descope Flow. This flow not only authenticates the user but also presents a consent screen showing the requested Google Calendar and Contacts scopes. Once the user approves, Descope connects the outbound apps behind the scenes, tying the user's identity to the exact API permissions required.

The result is a session token returned to the frontend. This token represents a verified user identity and their granted scopes. Every request from the frontend to the backend should include this session token, ensuring that the backend can validate the user and securely exchange it for outbound access tokens later.

Configure CrewAI tasks

With authentication and token management in place, the CrewAI application can now operate as a coordinated multi-agent system. In this setup, we've defined a crew that manages two independent agents, each with a distinct role and scope.

The Calendar Task is handled by the calendar_manager agent, which uses the Google Calendar access token to read or create events. This agent specializes in interpreting user intent around time and scheduling, ensuring that calendar operations are executed precisely.

The Contacts Task is handled by the contacts_finder agent, which uses the Google Contacts access token to search and retrieve detailed contact information. This agent is optimized for matching names, emails, or partial queries, and always returns structured, well-formatted results.

Each task runs in isolation, bound by the specific OAuth scopes granted through Descope. This means the calendar agent cannot access contacts, and the contacts agent cannot alter calendar events. The crew oversees the process, coordinating the agents' outputs and merging them into a unified result for the user.

Backend session validation

On the backend, validate the Descope session token using the Descope SDK. Verify the token and extract the trusted userId and session information. Only validated sessions can request Outbound App access tokens.

def validate_session(session_token):
    try:
        jwt_response = descope_client.validate_session(session_token=session_token, audience=os.getenv("VITE_CLIENT_ID"))
        print("Successfully validated user session:")
        print(jwt_response)
        return jwt_response
    except Exception as error:
        print("Could not validate user session. Error:")
        print(error)
        return None

Exchange session for access tokens

Once the session is validated, the backend exchanges it for scoped tokens for each Outbound App:

Calendar access token scoped to Calendar app permissions.
Contacts access token scoped to Contacts app permissions.

Descope handles OAuth flows and refresh logic, so the backend receives short-lived, scoped tokens without needing to store refresh tokens directly.

def get_outbound_token(app_id, user_id, session_token):
    """Fetch Google Calendar access token from Descope outbound token API."""
    project_id = os.getenv("VITE_DESCOPE_PROJECT_ID")
    management_key = os.getenv("DESCOPE_MANAGEMENT_KEY")
    url = "https://api.descope.com/v1/mgmt/outbound/app/user/token/latest"

    headers = {
        "Content-Type": "application/json",
        "Authorization": f"Bearer {project_id}:{session_token}",
    }
    payload = {
        "appId": app_id,
        "userId": user_id,
    }

    response = requests.post(url, headers=headers, json=payload)
    if response.status_code != 200:
        raise Exception(f"Failed to fetch token: {response.status_code} {response.text}")

    data = response.json()
    token_data = data["token"]
    access_token = token_data.get("accessToken")
    return access_token

Orchestrating agent security with Descope

With this setup, you have a secure, multi-agent CrewAI workflow. Each agent operates with least-privilege access, user consent is auditable, and the crew manager produces a unified output efficiently. To explore further or start experimenting right away, the sample app repo contains the complete codebase and configuration.

From here, you can start applying the same pattern to real use cases—for example, a sales workflow where one agent books meetings on Google Calendar while another enriches leads from your CRM, or a support workflow where an agent pulls customer details and another schedules follow-ups automatically. You might also explore adding new agents tied to other APIs, integrating project management or finance systems, or experimenting with CrewAI's orchestration features for more complex collaborations.

In short, this foundation gives you a practical way to scale multi-agent systems securely, while Descope handles the identity and access challenges behind the scenes.

Secure API Calling With Custom GPTs and Descope

Mrunank Pawar — Mon, 04 May 2026 15:00:00 +0000

This blog was originally published on Descope.

OpenAI's Custom GPTs offer a powerful way to create AI agents that can interact directly with your APIs through natural language conversations. Imagine you have a deployed FastAPI application that implements DevOps tools such as triggering CI/CD workflows, getting deployment logs, usage analytics, and other operational tasks. While integrating your API with an LLM sounds like a perfect task for a Model Context Protocol (MCP) server, MCP servers can be complex to implement and maintain, often posing security challenges that necessitate external middleware. Even FastAPI MCP wrappers introduce routing changes, CORS policies, and deployment overhead that quickly becomes its own project.

With Descope Inbound Apps, you're given a much simpler approach to establishing an OAuth compliant connection between your API and a custom GPT. In this article, we'll walk you through:

Securing your FastAPI backend with Descope JWT validation
Configuring a custom GPT to authenticate and interact with your protected APIs using scope-based authorization
Setting up your FastAPI application to act as a proxy for the Inbound App, so you maintain the authorization and the resource server under the same domain.

What you will build: a secure GPT assistant

By the end of this article, you will have a custom GPT that can securely interact with your prebuilt FastAPI endpoints through natural language conversations. The first time you submit a prompt in the current chat, you will be asked to authenticate and taken through the Descope inbound apps user consent flow. Note that if you configure a custom domain for your Descope project, your Descope-powered authorization server would run on your own custom domain, eliminating the need for this proxy setup. However, for this example, we will implement the proxy approach to understand the OAuth flow mechanics and provide an immediate out-of-the-box solution.

Once you are authenticated, you will be brought to the consent screen, which will display a list of scopes that you can consent to.

After you give consent, you will be seamlessly redirected back to your chat along with access and refresh tokens, which will be used when you call your API routes. The GPT will then ask for authorization to interface with the specific tool(s) which will be called to answer your prompt. Select Allow or Allow Always based on your personal preference.

When you make a request, your custom GPT sends it directly to your API with the access and refresh tokens it has. Your backend server then performs the scope validation and responds accordingly: if the token is invalid or expired, you'll get a 401 Unauthorized error; if the token is valid but lacks the necessary scopes for that specific endpoint, you'll receive a 403 Forbidden error. This approach keeps all the authorization decisions on the server side. In either case, the GPT will explain in natural language which error occurred when trying to generate a response. After you complete authentication and authorization, OpenAI will automatically manage your session. You can view and manually manage the connection and authorization status under Privacy Settings, which you can find in the drop-down menu next to the name of your GPT in the top left corner.

You can continue to submit prompts without reauthenticating until the authorization token issued to you by the Inbound App expires. The default session timeout is set to 10 minutes, but you can learn to adjust this later in the article.

Prerequisites

To complete the tutorial, you will need the following:

Python installed
A deployed FastAPI application; you can find a sample starter app here
ChatGPT Plus account

Setting up a Descope project

To create a new Descope project, sign up or sign in to the Descope console. If you just signed up for a new account, a new Descope project will be automatically created for you and you will find yourself on the Getting Started page of that project. To create a new project, click on your project's name in the top left corner of your Descope console, and select + Project from the dropdown. This is also where you can switch between projects. If you navigate to the Flows section, you will see that a handful of flows have automatically been created for you. Descope Flows are a no-code tool to build user authentication journeys. While you do not need to modify the default flows, you can choose to do so if you want to design a custom user journey.

You can access your project ID at any time by navigating to the Project section of the Descope console. You can copy the project ID from the General tab.

Configuring your application environment

In the root folder of your FastAPI application's project, create a .env file if you do not already have one, and add the following variables:

DESCOPE_PROJECT_ID=<Your Descope project ID> 
DESCOPE_INBOUND_APP_CLIENT_ID=<Inbound App client ID>
DESCOPE_INBOUND_APP_CLIENT_SECRET=<Inbound App client secret>
DESCOPE_API_BASE_URL="https://api.descope.com" # or your custom domain if one is configured in your project settings

Specify your Descope project ID. If you do not know where to find it, reference the previous section of this article. You will fill in the Inbound App client ID and secret later in this article.

Securing your app through token validation

Descope implements its session and refresh tokens as JSON web tokens (JWT). After your Custom GPT obtains a token from your Inbound App through the OAuth flow, your FastAPI backend needs to validate and accept these scoped tokens for authentication and authorization. The advantage of using this OAuth approach with Descope is that you get a complete consent flow and hosted login pages out of the box - no need to build your own authentication UI. You will implement a custom JWT authorizer into your FastAPI app that validates JWTs to make sure its signature is valid, it is not expired, and the audience and issuer claims match the expected resource server. Finally, the authorizer will enforce the scopes embedded in the token to control access to your API endpoints.

First, you will implement a simple exception handler. In your FastAPI application, create a new file and name it exceptions.py. Add these two exception definitions:

from fastapi import HTTPException, status

class UnauthenticatedException(HTTPException):
    def __init__(self):
        super().__init__(status_code=status.HTTP_401_UNAUTHORIZED, detail="Authentication required")

class UnauthorizedException(HTTPException):
    def __init__(self, detail: str = "Not authorized"):
        super().__init__(status_code=status.HTTP_403_FORBIDDEN, detail=detail)

Now let's implement the JWT authorizer. To validate the JWT, you will need to obtain a public key from the Descope JSON web key set (JWKS) endpoint. Your JWKS endpoint will look like this:

https://api.descope.com/<Your Descope Project ID>/.well-known/jwks.json

Create an auth.py file in your FastAPI app and add a TokenVerifier class. This class is used as a FastAPI dependency to validate incoming JWTs and, if requested by a route, enforce OAuth scopes.

At a high level, the TokenVerifier class extracts the bearer token from the authorization header, fetches the public key from your JWKS endpoint, and decodes and validates the JWT. It also uses the SecurityScopes library to validate and enforce the scopes embedded in the token:

from typing import Optional, List
import os
import jwt
from jwt import PyJWKClient
from fastapi import Depends
from fastapi.security import SecurityScopes, HTTPAuthorizationCredentials, HTTPBearer

from app.exceptions import UnauthenticatedException, UnauthorizedException

jwks_url = f"https://api.descope.com/{os.getenv('DESCOPE_PROJECT_ID')}/.well-known/jwks.json"

class TokenVerifier:
    def __init__(self):
        self.config = get_settings()
        self.jwks_client = PyJWKClient(jwks_url)
        self.allowed_algorithms = ["RS256"]

    async def __call__(
        self,
        security_scopes: SecurityScopes,
        # token injected by FastAPI Security, specified in the FastAPI route definition
        token: Optional[HTTPAuthorizationCredentials] = Depends(HTTPBearer())
    ):
        if token is None:
            raise UnauthenticatedException

        token = token.credentials

        key = self._get_signing_key(token)
        payload = self._decode_token(token, key)

        if security_scopes.scopes:
            self._enforce_scopes(payload, security_scopes.scopes)

        return payload

    def _get_signing_key(self, token: str):
        try:
            return self.jwks_client.get_signing_key_from_jwt(token).key
        except Exception as e:
            raise UnauthorizedException(f"Failed to fetch signing key: {str(e)}")

    # helper which calls jwt.decode()
    def _decode_token(self, token: str, key):
        try:
            project_id = os.getenv("DESCOPE_PROJECT_ID")
            issuer_candidates = [
                f'https://api.descope.com/v1/apps/{project_id}', 
                project_id
            ]
            return jwt.decode(
                token,
                key,
                algorithms=self.allowed_algorithms,
                issuer=issuer_candidates,
                audience=project_id
            )
        except Exception as e:
            raise UnauthorizedException(f"Token decoding failed: {str(e)}")

To restrict access to specific API routes based on the scopes carried by the incoming JWT token, add one more method to the TokenVerifier class that checks the token's scope claim. After successful validation, it reads the token's scope claim, compares it to the route's required scopes, and rejects the request if any are missing.

def _enforce_scopes(self, payload: dict, required_scopes: List[str]):
        scope_claim = payload.get("scope")
        if scope_claim is None:
            raise UnauthorizedException('Missing required claim: "scope"')

        scopes = scope_claim.split() if isinstance(scope_claim, str) else scope_claim
        missing = [scope for scope in required_scopes if scope not in scopes]

        if missing:
            raise UnauthorizedException(
                f'Missing required scopes: {", ".join(missing)}'
            )

Now let's hook up our JWT authorizer to the main file where you define your APIs. You can protect your API routes with token validation and/or scoping, restricting specific routes to tokens which have specific scopes. While scoping isn't mandatory for basic authentication, it's highly recommended when working with custom GPTs. This is because they handle 403 error responses fairly seamlessly, and they can gracefully inform users when they lack permissions. The scopes embedded in your access token will be set when creating your Descope Inbound App later in this article. For more insights on implementing robust security controls in enterprise applications, check out our enterprise MCP security challenges blog.

You may already have route protection configured, but if you do not, set it up as follows:

import urllib.request
import os
from app.auth import TokenVerifier

# Set a custom User-Agent to avoid being blocked by security filters or rate limiters.
opener = urllib.request.build_opener()
opener.addheaders = [('User-agent', 'Mozilla/5.0 (DescopeFastAPISampleApp)')]
urllib.request.install_opener(opener)

auth = TokenVerifier() 

@app.get("/api/private")
def private(auth_result: str = Security(auth)):
    # This API is now protected by our TokenVerifier object `auth`
    return auth_result

@app.get("/api/private-scoped/read")
def private_scoped(auth_result: str = Security(auth, scopes=['read:messages'])):
    """
    This is a protected route with scope-based access control.

    Access to this endpoint requires:
    - A valid access token (authentication), and
    - The presence of the `read:messages` scope in the token.
    """
    return auth_result

You should now have a working JWT authorizer implemented with your FastAPI app! For more detailed information on the functionality of this implementation, you can visit our Validating JWTs in FastAPI doc.

Configuring your FastAPI app to be an authorization server

Because the GPT requires the OAuth endpoints and the APIs to be hosted under the same domain name, you will use your FastAPI app as a proxy or middleware between the client application (Custom GPT) and the identity provider (Descope). If you are using a custom domain that's the same root domain as your FastAPI backend, you can skip this step.

You will expose three endpoints that your custom GPT will treat as its OAuth server:

GET /authorize – forwards the browser to Descope's /authorize endpoint
GET /api/oauth/callback – receives the authorization response from Descope and transforms it into the format expected by the custom GPT, including proper state parameter preservation and error handling for a seamless user experience.
POST /token – forwards the GPT's back-channel token exchange to Descope's /token endpoint

Authorization endpoint

The /authorize endpoint acts as the first step in the OAuth authorization code flow. When you initiate authentication through your custom GPT, this endpoint receives the OAuth parameters including response_type, redirect_uri, scope, and state. The endpoint performs several critical functions to ensure a secure OAuth flow:

Validates the incoming request parameters to ensure OAuth compliance and prevents malformed or malicious requests.
Dynamically constructs the callback URL based on the request's host, providing flexibility for different deployment environments.
Transforms the request into Descope's expected format by adding the necessary client credentials and redirect URI.
Redirects you to Descope's authorization server, where you can authenticate and authorize the application.

This proxy architecture provides several key benefits: centralized control over the OAuth flow, enhanced security through request validation and sanitization, and the flexibility to add custom logging and error handling.

@app.get("/authorize")
async def authorize(
    request: Request,
    response_type: Optional[str] = None,
    redirect_uri: Optional[str] = None,
    scope: Optional[str] = None,
    state: Optional[str] = None
):
    """
    OAuth 2.0 Authorization Endpoint - Proxies to Descope

    This endpoint forwards OAuth authorization requests to Descope's Inbound Apps.
    """
    try:
        # Validate required parameters
        if not redirect_uri or not response_type:
            print(f"Missing required parameters")
            raise HTTPException(
                status_code=400
            )

        # Validate response_type
        if response_type != "code":
            print(f"Unsupported response_type: {response_type}")
            raise HTTPException(
                status_code=400
            )

        # Get client ID from environment or use the provided one
        descope_client_id = os.getenv("DESCOPE_INBOUND_APP_CLIENT_ID")
        if not descope_client_id:
            print("OAuth client credentials not configured")
            raise HTTPException(
                status_code=500,
            )

        # Get the base URL from the request
        base_url = str(request.base_url).rstrip('/')
        callback_url = f"{base_url}/api/oauth/callback"

        # Construct query parameters
        params = {
            "client_id": descope_client_id,
            "redirect_uri": callback_url,
            "response_type": "code",
            "scope": scope or "openid",
            "state": state or ""  # Just pass through the state parameter
        }

        # Build the full URL with query parameters
        query_string = "&".join([f"{k}={v}" for k, v in params.items()])
        full_url = f"https://api.descope.com/oauth2/v1/apps/authorize?{query_string}"

        print(f"Redirecting to Descope: {full_url}")

        # Redirect to Descope's authorization endpoint
        return RedirectResponse(url=full_url)

    except HTTPException:
        raise
    except Exception as error:
        print(f"Authorization endpoint error: {error}")
        raise HTTPException(
            status_code=500
        )

Token exchange endpoint

The /token endpoint performs the OAuth 2.0 token exchange process, handling the conversion of authorization codes into access tokens. When your custom GPT sends a token exchange request, this endpoint manages the complete flow from validation to token retrieval. The endpoint handles several key operations during the token exchange:

Parses the incoming request body containing the authorization code, client credentials, and grant type from your custom GPT.
Validates all required parameters including the grant type and client credentials to ensure the request meets OAuth 2.0 standards.
Dynamically constructs the redirect URI to match the original authorization request, maintaining consistency across the flow.
Forwards the validated request to Descope's token server with proper client credentials and authorization code, acting as a trusted intermediary.

This centralized architecture enables detailed request/response logging for debugging, allows for custom validation and transformation of the OAuth flow, and maintains full compatibility with standard OAuth implementations while giving you complete control over the token exchange process.

@app.post("/token")
async def token(
    request: Request
):
    """
    OAuth 2.0 Token Endpoint - Proxies to Descope

    This endpoint forwards token exchange requests to Descope's Inbound Apps.
    """
    print("Token exchange request received")

    try:
        # Parse the request body based on content type
        content_type = request.headers.get("content-type", "")
        print(f"Request content-type: {content_type}")

        if "application/json" in content_type:
            body = await request.json()
        elif "application/x-www-form-urlencoded" in content_type:
            form_data = await request.form()
            body = dict(form_data)
        else:
            # Try to parse as JSON first, then as form data
            try:
                body = await request.json()
            except:
                form_data = await request.form()
                body = dict(form_data)

        grant_type = body.get("grant_type")
        code = body.get("code")
        client_id = os.getenv("DESCOPE_INBOUND_APP_CLIENT_ID")
        client_secret = os.getenv("DESCOPE_INBOUND_APP_CLIENT_SECRET")

        # Validate required parameters
        if not grant_type or not code or len(client_id) == 0 or len(client_secret) == 0:
            raise HTTPException(
                status_code=400
            )

        # Only support authorization_code grant type
        if grant_type != "authorization_code":
            raise HTTPException(
                status_code=400
            )

        # Get the base URL from the request
        base_url = str(request.base_url).rstrip('/')
        callback_url = f"{base_url}/api/oauth/callback"

        # Forward the request to Descope's token endpoint
        token_request_body = {
            "grant_type": "authorization_code",
            "client_id": client_id,
            "client_secret": client_secret,
            "code": code,
            "redirect_uri": callback_url
        }

        descope_url = "https://api.descope.com/oauth2/v1/apps/token"

        async with httpx.AsyncClient() as client:
            print("Sending request to Descope token endpoint")
            response = await client.post(
                descope_url,
                data=token_request_body,
                headers={"Content-Type": "application/x-www-form-urlencoded"}
            )

            descope_data = response.json()

            # If Descope returned an error, log it
            if response.status_code >= 400:
                print(f"Descope token exchange failed: {descope_data}")

            # Return the response from Descope
            return descope_data

    except HTTPException:
        raise
    except Exception as error:
        print(f"Token endpoint error: {error}")
        raise HTTPException(
            status_code=500
        )

Callback endpoint

The /api/oauth/callback endpoint serves as the bridge in the OAuth 2.0 authorization code flow, receiving the authorization response from Descope and transforming it into the format expected by your custom GPT. When Descope redirects the user's browser back to this endpoint, it performs several critical operations:

Extracts the authorization code and state parameter from Descope's callback response.
Validates the received parameters and handles any OAuth errors returned by Descope during the authorization process.
Constructs a properly formatted redirect URL that includes the authorization code and preserved state parameter in the format your custom GPT expects.
Issues a 307 Temporary Redirect response to the user's browser, which automatically follows the redirect to your custom GPT's callback URL.

The 307 redirection mechanism is crucial because it preserves the HTTP method and request body while ensuring that your custom GPT receives the authorization data in exactly the format it needs to complete the token exchange.

@app.get("/api/oauth/callback")
async def oauth_callback(
    code: Optional[str] = None,
    state: Optional[str] = None,
    error: Optional[str] = None,
    error_description: Optional[str] = None
):
    """
    OAuth 2.0 Callback Endpoint

    Handles the callback from Descope and redirects back to Custom GPT.
    """
    try:
        # Handle errors from Descope
        if error:
            raise HTTPException(
                status_code=400,
                detail={
                    "error": error,
                    "error_description": error_description
                }
            )

        if not code:
            raise HTTPException(
                status_code=400,
                detail={
                    "error": "invalid_request",
                    "error_description": "No authorization code received"
                }
            )

        # Custom GPT callback URL - obtained after creating your GPT
        custom_gpt_callback = "<Your GPT callback URL>"

        # Build redirect URL back to Custom GPT
        redirect_url = f"{custom_gpt_callback}?code={code}"
        if state:
            redirect_url += f"&state={state}"

        return RedirectResponse(url=redirect_url)

    except HTTPException:
        raise
    except Exception as error:
        raise HTTPException(
            status_code=500,
            detail={
                "error": "server_error",
                "error_description": "Internal server error"
            }
        )

Setting up an Inbound App

Now we will set up the Descope part of this backend by creating an Inbound App. Inbound Apps enable you to turn your application into an identity provider (IdP). The Inbound App will handle the OAuth flow, endpoints, and consent mechanisms for you, allowing you to easily manage authentication and define granular permission scopes at the user or tenant level. When you configure your custom GPT, it will use a scoped OAuth token generated by your Inbound App to access the APIs that it is authorized to access.

To create a new Descope Inbound App, navigate to the Inbound Apps page of your Descope console. Select the blue + Inbound App button on the right side of the screen, and give your new Inbound App a name and optional description.

Scoping your Inbound App

After you create your Inbound App, you will be able to see all the settings and details. If you scroll down to the Scopes section, this is where you will define what scopes will be embedded in the JWT token provided to your application. The scope names you set here should exactly match the scopes that are required by the API routes that you wish to give your token access to.

Client ID and secret

Next, scroll down to the Connection Information section, and here you will see the configuration data needed to integrate your backend app with the Inbound App. For example, notice the Authorization URL and Token URL are the same URLs that we routed to in the /authorize and /token routes of our FastAPI app. The most important values here are the Client ID and Client Secret. Copy and paste those values into your .env file for your DESCOPE_INBOUND_APP_CLIENT_ID and DESCOPE_INBOUND_APP_CLIENT_SECRET variables, respectively.

User consent flow

Notice also the Flow Hosting URL. This URL points to the exact Descope flow that will be used to define the authentication and consent user journey. If you navigate over to the Flows section of the Descope console, you will see that once you created your first Inbound App, Inbound App consent flows were also automatically created for you. The default user consent flow was the one demonstrated at the beginning of this article.

Custom session token expiration

By default, the session token issued by your Inbound App will expire 10 minutes after the time of issuance. If you want to adjust this, scroll down to the last section of the Inbound App settings, called Session Management. Select the Custom option, and then modify the Session Token Timeout.

Your Inbound App is now fully configured and ready to use!

Configuring your custom GPT

GPTs enable you to create a tailored version of ChatGPT based on custom instructions, actions, or context. For this article, we are going to be configuring a GPT which will act as your personal DevOps assistant. We will essentially be building an AI agent, but one that knows how to interact with your specific APIs. To create a new GPT, open the ChatGPT homepage and select the GPTs tab in the left sidebar. This will bring you to the homepage of existing publicly available GPTs. Select the + Create button in the upper right corner.

Select the Configure tab on your GPT. Enter a name for your GPT, and optionally provide an icon, description, instructions, prompt starters, and knowledge (extra context) on this page.

Configuring OAuth for your GPT

Scroll all the way down to the bottom of the Configure page, and under Actions, select the Create new action button. This action will be the mechanism through which your GPT will interface with your application. Once on the action definition page, click on the Authentication dropdown menu and select OAuth as your authentication type. This will open up a new window, where you will configure the OAuth connection between this GPT and your API. You will need to specify the following:

Authorization URL: this is your API route that handles the initial call to the Descope authorize endpoint (e.g. app/authorize).
Token URL: this is the API route that handles the code and token exchange at the Descope token endpoint (e.g. app/token).
Token Exchange Method: Make sure Default (POST request) is selected. Leave the Client ID, Client Secret, and Scope fields blank. Your backend application will take care of these parts.

Click Save once you have filled out the appropriate fields.

Creating an OpenAPI spec

Once you have configured the OAuth credentials, you will need to provide an OpenAPI 3.1.0 spec in the textbox titled Schema. An OpenAPI spec is a document written in a machine readable format like YAML or JSON that describes your API endpoints and how to call them with the appropriate parameters, request/response formats, authentication methods, and other relevant information. For an example of an OpenAPI spec in either a JSON or YAML format, visit this Descope sample app. FastAPI easily generates a JSON file for you, simply enter the URL where your application is hosted followed by /openapi.json. If you utilize this option, you will have to add a servers object, where you will tell the GPT the URL where it can find your API server.

"servers": [
    {
      "url": "https://<Your base URL>"
    }
]

To complete the process of creating your GPT, click the black Create button in the top right corner. You will then have the option of keeping your GPT private, or sharing it with others. This is up to your personal preference, but sharing it will require you to add a privacy policy. After you create your GPT, navigate to GPTs > My GPTs then click the pencil icon on your GPT and scroll down to the same place where you created your action earlier. Now you should see an action with your base URL listed, and under it you will see a Callback URL. Copy this callback URL and paste it into the custom_gpt_callback variable in the /api/oauth/callback route.

GPTs with Descope

Now you can securely interact with your FastAPI routes through an LLM – all without having to spin up an MCP server. This approach provides a robust, secure, and maintainable way to connect custom GPTs to your protected APIs. By leveraging Descope's Inbound Apps and OAuth capabilities, you can create sophisticated AI agents without the complexity of MCP servers.

To explore Descope further, sign up for a free account, join our developer Slack community, or follow us on LinkedIn.

Authenticating CLI Tools With Descope

Mrunank Pawar — Fri, 01 May 2026 15:00:00 +0000

This blog was originally published on Descope.

Need to add authentication to your command-line tool? Most command-line applications rely on API keys, manual token management, and other methods that create friction for users who just want to get authenticated.

In this blog, we'll walk through the challenges of CLI authentication and how to implement it seamlessly with Descope Inbound Apps. We'll also show how to bring OAuth 2.0 directly to your CLI app with code examples in Go.

What is CLI authentication?

In the context of command-line applications, authentication presents a unique challenge: how do you securely authenticate users in an environment that traditionally lacks the interactive elements of web applications?

Most CLI tools handle this via the tedious storage of API keys in configuration files or environment variables. This approach creates friction for users and introduces security risks as a byproduct of storing credentials in plain text or across systems.

Consider this scenario: You switch to a new laptop and need to set up various CLI applications, such as deployment tools, database clients, cloud service CLIs, and internal company tools. For each of these tools, you will need to generate API keys from different dashboards, make new cryptic environment variables to store these values, and save them in obscure configuration files. Now, you have API keys scattered across config files and tokens with overly broad permissions because of mishandled scoping. And eventually when you leave your company, IT will have no way to revoke access to these tools with these keys. This is the tax of API key storage for authentication and the potential security nightmare.

CLI authentication using OAuth 2.0 solves this by bringing the familiar browser-based authentication flow directly to terminal applications. Users are able to authenticate through the same OAuth providers and flows they use in web applications.

How authentication looks with Descope Inbound Apps

Inbound apps in Descope turn your application into an identity provider, making it compliant with OAuth standards and allowing third-party applications, APIs, and tools to authenticate and access authorized user data through a user consent flow with scope-based access control. They also handle OAuth flows and contain the necessary credentials for OAuth parameters, redirect URIs, and authentication settings. If you would like to learn more, check out our blog on Inbound Apps.

When a user runs an authentication command, or any command that requires authentication to use, the CLI tool generates an OAuth authorization URL corresponding to your Inbound App and opens the link in the user's default browser. The user then proceeds to complete the standard OAuth flow in their browser, signing in and authorizing the inbound app. Finally, the CLI app will receive the authorization callback with the necessary tokens to act on the user's behalf.

Example: CLI authentication in Golang

Now that we understand the purpose of CLI authentication and what our authentication flow looks like with Descope Inbound Apps, we can implement our own sample application.

Prerequisites and set up

Before we dive into our CLI application, make sure you have Go 1.19 or later and a configured Descope Inbound App. If you're new to Descope, no problem. To get started, sign up for a free account on Descope Get started docs.

Step 1: Create your Descope Inbound App

Navigate to your Descope console and click on Inbound Apps in the left sidebar.

Click the + Inbound App button and give your app a name. Once created, you can configure scopes and view your connection information.

Step 2: Set up your Go command-line app with Cobra

To initialize your new Go module and install the Cobra generator, run:

go mod init <your-module-name> &&
go install github.com/spf13/cobra-cli@latest &&
go get github.com/spf13/cobra &&
cobra-cli init

Now, you will see your basic project structure including your main application file (main.go) and a cmd folder containing your root.go file. You should see the following in the root.go file:

package cmd

import (
    "os"

    "github.com/spf13/cobra"
)

var rootCmd = &cobra.Command{
    Use:   "clidemo",
    Short: "A brief description of your application",
    Long: `A longer description that spans multiple lines and likely contains
examples and usage of using your application. For example:

Cobra is a CLI library for Go that empowers applications.
This application is a tool to generate the needed files
to quickly create a Cobra application.`,
    Run: func(cmd *cobra.Command, args []string) {},
}

func Execute() {
    err := rootCmd.Execute()
    if err != nil {
        os.Exit(1)
    }
}

func init() {
    rootCmd.Flags().BoolP("toggle", "t", false, "Help message for toggle")
}

For the purposes of the demonstration, we will be using the Run in rootCmd in order to run our authentication flow upon program execution.

Step 3: Configuring your Inbound App

Connecting to your Inbound App requires setting up the relevant credentials. The form of the configuration will look like this:

type InboundAppConfig struct {
    Issuer                            string
    JwksURI                          string
    AuthorizationEndpoint            string
    ResponseTypesSupported           []string
    SubjectTypesSupported            []string
    IdTokenSigningAlgValuesSupported []string
    CodeChallengeMethodsSupported    []string
    TokenEndpoint                    string
    UserInfoEndpoint                 string
    ScopesSupported                  []string
    ClaimsSupported                  []string
    RevocationEndpoint               string
    RegistrationEndpoint             string
}

// then, in your Run function, define your configuration
// the base URL and project ID should be defined as environmental variables
config := InboundAppConfig{
    Issuer:                            DESCOPE_BASE_URL + "/v1/apps/" + DESCOPE_PROJECT_ID,
    JwksURI:                          DESCOPE_BASE_URL + "/" + DESCOPE_PROJECT_ID + "/.well-known/jwks.json",
    AuthorizationEndpoint:            DESCOPE_BASE_URL + "/oauth2/v1/apps/authorize",
    ResponseTypesSupported:           []string{"code"},
    SubjectTypesSupported:            []string{"public"},
    IdTokenSigningAlgValuesSupported: []string{"RS256"},
    CodeChallengeMethodsSupported:    []string{"S256"},
    TokenEndpoint:                    DESCOPE_BASE_URL + "/oauth2/v1/apps/token",
    UserInfoEndpoint:                 DESCOPE_BASE_URL + "/oauth2/v1/apps/userinfo",
    ScopesSupported:                  []string{"openid"},
    ClaimsSupported: []string{
        "iss",
        "aud",
        "iat",
        "exp",
        "sub",
        "name",
        "email",
        "email_verified",
        "phone_number",
        "phone_number_verified",
        "picture",
        "family_name",
        "given_name",
    },
    RevocationEndpoint:    DESCOPE_BASE_URL + "/oauth2/v1/apps/revoke",
    RegistrationEndpoint:  DESCOPE_BASE_URL + "/v1/mgmt/inboundapp/app/" + DESCOPE_PROJECT_ID + "/register",
}

This is a blueprint for the Inbound App, identifying it by the aforementioned connection information.

Next, we create a handler for OpenID Connect discovery requests through the .well-known/openid-configuration endpoint.

http.HandleFunc("/.well-known/openid-configuration", func(w http.ResponseWriter, r *http.Request) {
    w.Header().Set("Content-Type", "application/json")
    w.Header().Set("Access-Control-Allow-Origin", "*")
    w.Header().Set("Access-Control-Allow-Methods", "GET, OPTIONS")
    w.Header().Set("Access-Control-Allow-Headers", "Content-Type, mcp-protocol-version")

    if r.Method == http.MethodOptions {
        w.WriteHeader(http.StatusNoContent)
        return
    }

    json.NewEncoder(w).Encode(config) // using our Inbound App config
})

Step 4: Generating an OAuth URL

Creating the parameters for the OAuth URL requires creating an OAuth2 CSRF state, a PKCE code verifier, and a code challenge. The state prevents Cross-Site Forgery attacks, verifying that the state remains the same when starting the OAuth2 flow and when redirecting back to the app. The Proof Key for Code Exchange code verifier is hashed in the code challenge, and the server verifies the two values are corresponding when exchanging the authorization code for tokens.

To create these parameters, we will make a util.go class for the associated functions.

func randomString(n int) string { // used to generate the state & verifier
    b := make([]byte, n)
    rand.Read(b)
    return base64URLEncode(b)
}

func sha256Hash(input string) []byte { // for hashing the verifier
    h := sha256.New()
    h.Write([]byte(input))
    return h.Sum(nil)
}

func base64URLEncode(data []byte) string { // for encoding the string & hash
    return strings.TrimRight(base64.URLEncoding.WithPadding(base64.NoPadding).EncodeToString(data), "=")
}

Then, in root.go, we create the authorization URL using the authorization endpoint and params:

state := randomString(16)
codeVerifier := randomString(64)
codeChallenge := base64URLEncode(sha256Hash(codeVerifier))

params := url.Values{
    "response_type":         {"code"},
    "client_id":             {DESCOPE_CLIENT_ID},
    "redirect_uri":          {REDIRECT_URI},
    "scope":                 {""},
    "state":                 {state},
    "code_challenge":        {codeChallenge},
    "code_challenge_method": {"S256"},
}

authURL := config.AuthorizationEndpoint + "?" + params.Encode()

Step 5: Authorization callback and retrieving tokens

Now, we will set up a channel to receive our authorization code and exchange it for tokens. Go makes this elegant:

codeChan := make(chan string) // channel receiving strings
srv := &http.Server{Addr: ":8080"} // server to listen to

Since the redirect URI is configured to http://localhost:8080/callback (can be configured to a custom redirect URI), we set up an HTTP server listening on port 8080 to handle the OAuth callback response. We then handle the OAuth callback through a couple of steps:

Error handling

Verify that the OAuth provider did not send back any error.

if errorCode := r.URL.Query().Get("error"); errorCode != "" {
    errorDesc := r.URL.Query().Get("error_description")
    log.Printf("OAuth Error: %s - %s", errorCode, errorDesc)
    http.Error(w, fmt.Sprintf("OAuth error: %s - %s", errorCode, errorDesc), http.StatusBadRequest)
    return
}

State validation

Compare the state parameter of the callback URL to the originally generated CSRF state.

if r.URL.Query().Get("state") != state {
    http.Error(w, "Invalid state", http.StatusBadRequest)
    return
}

Authorization code extraction

Look for the code parameter of the callback URL provided after successful login.

code := r.URL.Query().Get("code")
if code == "" {
    http.Error(w, "Missing code", http.StatusBadRequest)
    return
}

Success!

Receive the authorization code and output a success on the page for visual representation.

fmt.Fprintln(w, "Login successful! You may close this browser window.")
codeChan <- code

Opening the browser, posting, and fetching the token

We want the user to interact with the authorization URL to proceed with the callback. In order to open the user browser, we add the following to our util.go:

func openBrowser(url string) {
    var cmd string
    var args []string

    switch runtime.GOOS {
    case "windows":
        cmd = "rundll32"
        args = []string{"url.dll,FileProtocolHandler", url}
    case "darwin":
        cmd = "open"
        args = []string{url}
    default:
        cmd = "xdg-open"
        args = []string{url}
    }

    exec.Command(cmd, args...).Start()
}

The function will call the corresponding shell command to open the user's browser for their respective operating system. Our next steps to retrieve the token response will be to post a request to the token endpoint of the following form:

"grant_type":     {"authorization_code"}, // grant by auth code
"client_id":      {DESCOPE_CLIENT_ID},    // your inbound app client id
"code":           {code},                 // the code fetched from the channel
"redirect_uri":   {REDIRECT_URI},         // your redirect URI
"code_verifier":  {codeVerifier},         // previously calculated verifier

And, putting it all together with a final authentication message on the CLI app:

openBrowser(authURL)
code := <-codeChan
srv.Shutdown(context.Background())

resp, err := http.PostForm(config.TokenEndpoint, url.Values{
    "grant_type":    {"authorization_code"},
    "client_id":     {DESCOPE_CLIENT_ID},
    "code":          {code},
    "redirect_uri":  {REDIRECT_URI},
    "code_verifier": {codeVerifier},
})
if err != nil {
    log.Fatalf("Token exchange error: %v", err)
}
defer resp.Body.Close()

if resp.StatusCode != http.StatusOK {
    log.Fatalf("Token exchange failed with status: %d", resp.StatusCode)
}

var tokenResp map[string]interface{} // response format in Go
if err := json.NewDecoder(resp.Body).Decode(&tokenResp); err != nil {
    log.Fatalf("Invalid token response: %v", err)
}

fmt.Println("Welcome! You have successfully authenticated with Descope")

Visualizing the Flow

Run your application:

go run main.go

Then, your browser will open a new page:

Next, you will see the browser output after authenticating the user and successfully authorizing the Inbound App:

Login successful! You may close this browser window.

Finally, the CLI app will print a success message after receiving the authorization callback:

Welcome! You have successfully authenticated with Descope Inbound Apps.

If you would like to see the full sample code, it is available in our Github repository.

CLI authentication made simpler with Descope

CLI auth with Descope Inbound Apps makes your command-line authentication flow smoother, safer, and free of user friction. Users will be able to authenticate with the same OAuth providers and flows they use in web applications, providing a seamless and familiar experience. Sign up for a Free Forever Descope account now to start creating frictionless CLI authentication flows. You can also dive into more auth best practices by joining AuthTown, our community of developers building better identity experiences. Got questions about Descope? Book time with our auth experts.

Adding Authentication Middleware With Descope

Mrunank Pawar — Wed, 29 Apr 2026 15:00:00 +0000

This blog was originally published on Descope.

Looking to implement authentication middleware in your app? Most modern frameworks support middleware functions that let you intercept user requests, verify tokens, and control access—all in a centralized way.

In this blog, we'll walk through how authentication middleware works and how to implement it effectively using code examples in Node.js and Python. Once you understand the basics, we'll show how Descope's tools can streamline the process with out-of-the-box support for token validation, role checks, and more.

What is authentication middleware in web apps

In the context of web development, authentication middleware is a function that intercepts incoming requests and runs logic before or after those requests reach your application's core handlers. Middleware gives you a centralized way to manage access control, freeing up developer time to focus on business logic instead of duplicating auth checks across routes.

Most modern frontend and backend frameworks support this concept. You typically register a function—similar to a callback—that's triggered with every request. This can happen before the request reaches a controller or after the response is generated.

Within this middleware function, you can inspect request headers (like Authorization) and validate session tokens or permissions before allowing access to protected routes.

Example: Authentication middleware in Node.js

Let's look at how to build simple authentication middleware using Express in a Node.js app. This middleware intercepts requests, checks for an authorization header, and validates the session token before passing the request to the next handler.

var express = require('express')
var app = express()

var validateJwt = function(token) {
  // validation logic
  return true;
}

var authMiddleware = function (req, res, next) {
  req.isValidSession = validateJwt(req.headers.authorization)
  next()
}

app.use(authMiddleware)

app.get('/', function (req, res) {
  var responseText = 'Hello World!<br>'
  responseText += '<small>Session Valid:' + req.isValidSession + '</small>'
  res.send(responseText)
})

app.listen(3000)

In this example, the authMiddleware function runs on every request. It extracts the token from the Authorization header, runs a validation check, and attaches the result (isValidSession) to the request object. This setup gives you a lightweight way to apply authentication logic across all routes in your Express app.

Adding Descope authentication to Node.js middleware

Now that we understand how middleware works, we can use it to implement robust authorization and authentication middleware by validating user sessions on every request.

Descope makes this easier by providing SDKs that handle session and token validation. Instead of repeating auth logic across your app, you can centralize it in a single middleware function. That way, each incoming request is automatically checked for a valid access token or refresh token before hitting protected routes.

Here's how to build authentication middleware using the Descope Node.js SDK:

authentication.js

import DescopeClient from '@descope/node-sdk';

export class DescopeMiddleware {
  constructor(projectId) {
    this.descopeClient = DescopeClient({ projectId: projectId});
  }

  validate(token) {
    try {
      const authInfo = await descopeSdk.validateSession(sessionToken);
      console.log("Successfully validated user session:");
      console.log(authInfo);
    } catch (error) {
      console.log("Could not validate user session " + error);
    }
  }
}

app.js

import express from 'express';
import DescopeMiddleware from './authentication.js';

const app = express();
const authMiddleware = new DescopeMiddleware('__PROJECT_ID__');

app.use(authMiddleware.validate());

app.get('/', (req, res) => {
  res.send('main');
});

app.listen(3000, () => {
  console.log("Express Running port 3000")
});

This pattern helps you manage authentication in one place. It also improves maintainability by offloading session validation to Descope's SDK, allowing you to focus on application logic.

Using Descope decorators in Python

Python decorators are a powerful way to wrap additional behavior around existing functions, making them especially useful for building authentication middleware in Python web frameworks.

A decorator takes a function as input, extends or modifies its behavior, and returns a new function. This allows you to centralize logic, such as logging, validation, or—in our case—authentication, without cluttering every route with repeated code.

Here's a basic example of how decorators work:

def my_decorator(func):
    def wrapper():
        print("Something is happening before the function is called.")
        func()
        print("Something is happening after the function is called.")
    return wrapper

@my_decorator
def say_hello():
    print("Hello!")

say_hello()

To use a decorator, you simply annotate a function with @decorator_name. When you call that function, Python actually runs the wrapper logic defined inside the decorator. In this case, calling say_hello() produces the following output:

> Something is happening before the function is called.
> Hello!
> Something is happening after the function is called.

This structure is ideal for building authentication middleware in frameworks like Flask, FastAPI, or Django, where decorators can be applied directly to route functions to enforce login or permission checks.

Example: Descope Python decorator

You could write your own authentication middleware using decorators in Flask, FastAPI, or Django. But to save time, Descope provides prebuilt decorators that handle session validation, role enforcement, and other identity checks out of the box.

Here's an example of using Descope's @descope_validate_auth decorator to protect a route that requires authentication:

# This needs authentication
@APP.route("/private")
@descope_validate_auth(
    descope_client
)  # Can add permissions=["Perm 1"], roles=["Role 1"], tenant="t1" conditions
def private():
    return Response("<h1>Restricted page, authentication needed.</h1>")

This decorator automatically checks the user's JWT. If the token doesn't meet the conditions—such as having the correct roles or permissions—Descope will return a 401 Unauthorized response without running the route handler.

Descope also provides other decorators that extend the behavior of your routes. For example, the @descope_full_login decorator can trigger a Descope Flow:

@APP.route("/login", methods=["GET"])
@descope_full_login(
    project_id=PROJECT_ID,
    flow_id="sign-up-or-in",
    success_redirect_url="http://dev.localhost:9010/private",
)
def login():
    # Nothing to do! this is the MAGIC!
    pass

Need to handle logout? The @descope_logout decorator clears the user's session:

@APP.route("/logout")
@descope_logout(descope_client)
def logout():
    return Response("<h1>Goodbye, logged out.</h1>")

With just a few lines of code, you can use decorators to handle user authentication and session flow without repeating logic across your app.

Authentication middleware made simpler with Descope

Authentication middleware lets you centralize and automate how your app handles access control. By intercepting requests and validating tokens before they hit protected routes, middleware simplifies security and improves the user experience.

Descope gives you tools to build and manage this layer more efficiently. Whether you prefer writing your own middleware or using prebuilt decorators, you can plug in Descope's SDKs and flows to streamline session validation, role enforcement, and login logic.

Want to add authentication to your app without reinventing the wheel? Sign up for a Free Forever Descope account to get started. If you have questions or want to learn more about authentication best practices, book time with our auth experts.

Add Authentication and SSO to Your Shiny App

Mrunank Pawar — Mon, 27 Apr 2026 15:00:00 +0000

This blog was originally published on Descope.

Shiny lets you easily build web apps for data science using R and Python without the need for any web development experience. You can deploy these applications on your own web server or use Posit Connect to deploy them directly from your IDE.

Although deploying the applications is straightforward, it's also vital to set up proper access control for these applications to ensure that only authenticated users can view and interact with the data. Integrating single sign-on (SSO) with Shiny apps can provide a seamless authentication experience for the users. As these apps are often used by different business or enterprise users who might need to log in with their own identity provider (IdP), SSO allows them to use their existing credentials to log in.

Descope offers a no-code Customer Identity Platform (CIAM) that lets you easily define a customized workflow for sign-up, login, multi-factor authentication (MFA), SSO, and Security Assertion Markup Language (SAML).

In this tutorial, you'll learn how to implement authentication and SSO in a Shiny app.

Prerequisites

Before starting, you need to do the following:

Install RStudio on your development machine.
Install Posit Connect locally and configure its license. This tutorial uses an on-prem installation of Posit Connect on AWS, but alternatively, you can sign up for Posit Connect Cloud and use it to follow along.
Sign up for a free Descope account.

Set up Descope

Before you can integrate Descope authentication into your Shiny application, you need to define an authentication flow using the Descope portal.

Sign up for a free Descope account if you don't already have one, and follow the Getting Started wizard to create a new flow. In the wizard, first, choose Consumers as the target audience for your app:

Next, choose the authentication methods you want to use. In this tutorial, you'll use Magic Link and SSO as the authentication method. You can change these settings in the future if you like:

Skip the next step that prompts you to choose an MFA method by clicking Go ahead without MFA. In the next step, review the selected settings and click Next to generate the authentication flow:

Create a Shiny app

In this tutorial, you'll create a personal finance application using Shiny and add Descope authentication. The Shiny app will let you upload a CSV file containing month-wise expense data, view a bar chart with monthly expense trends, and also analyze category-wise expenses.

Since the tutorial focuses on adding authentication, you can clone the starter code with the personal finance Shiny app. In the terminal, navigate to the project directory and check out the starter branch.

cd personal-finance-shiny
git checkout starter

Open the application using RStudio and attempt to run the starter app. When you run it for the first time, it will prompt you to install the required packages. After you install the packages and rerun the app, you'll notice that you're directly taken to the dashboard page without authentication:

Next, click on the Publish button in RStudio to deploy the app on Posit Connect.

Before you can publish the Shiny app, you need to connect your Posit Connect account by clicking Add new account and choosing Posit Connect. Enter the Posit Connect server URL and click Next to connect the account.

You'll be redirected to the web browser to confirm the linking between RStudio and Posit Connect. Click Connect to link the account.

After confirming the connection in the browser, navigate back to RStudio and click Connect Account to verify the account.

Finally, select the connected account, provide a title for the app, and click Publish to deploy the application.

The dashboard of the app has the following components:

The left section lets you upload a CSV file containing personal expense data. The GitHub repo contains a sample CSV that you could use for testing.
When you upload the CSV file, the right section lets you view and analyze the category-wise expenses based on the uploaded data.

Implement vanilla authentication with Descope

You've deployed the app to Posit Connect and can now add authentication methods to access it using Descope. In this section, you'll add auth using magic links and email OTP for simplicity. You can configure and use other authentication methods too but we will focus on magic links and OTP for this tutorial.

Descope offers a WebJS component to integrate its auth flows with HTML-based web apps. You can easily integrate the WebJS component with your Shiny app by adding a custom JavaScript widget.

In your R project, create a www/descope-auth.js file, add the following content to create a container for the Descope element, and set success and failure listeners:

// www/descope-auth.js
Shiny.addCustomMessageHandler('initDescopeAuth', function (config) {
  const wcElement = document.createElement('descope-wc');
  wcElement.setAttribute('project-id', config.projectId);
  wcElement.setAttribute('flow-id', config.flowId);
  wcElement.setAttribute('theme', config.theme);

  wcElement.addEventListener('success', function (e) {
    const user = e.detail.user;
    Shiny.setInputValue(config.successInput, user);
  });

  wcElement.addEventListener('error', function (err) {
    console.error('Authentication error:', err);
    Shiny.setInputValue(config.errorInput, err);
  });

  const container = document.getElementById(config.containerId);
  if (container) {
    container.innerHTML = ''; // Clear any previous instances
    container.appendChild(wcElement);
  }
});

Next, you need to update the UI definition to include the @descope/web-component and descope-auth.js JS scripts. Update the app.R file by replacing it with the following code snippet:

ui <- fluidPage(
  useShinyjs(), # For dynamic UI control
  tags$head(
    tags$script(src = "https://unpkg.com/@descope/web-component@3.32.0/dist/index.js"),
    tags$script(src = "descope-auth.js") # Include custom JavaScript
  ),
  titlePanel("Personal Finance Dashboard with Descope Auth"),

  # Descope Authentication UI
  div(id = "authContainer"),

  hidden(
    div(
      id = "appContent",
      sidebarLayout(
        sidebarPanel(
          fileInput("file", "Upload Expense Data (CSV)", accept = ".csv"),
          selectInput("category", "Select Category:", choices = NULL),
          actionButton("analyze", "Analyze")
        ),
        mainPanel(
          tabsetPanel(
            tabPanel("Overview", plotOutput("expenseTrend"), tableOutput("summaryTable")),
            tabPanel("Category Analysis", plotOutput("categoryTrend"), tableOutput("categoryTable"))
          )
        )
      )
    )
  )
)

Finally, you need to update the server definition to initialize the Descope web component and implement success and failure callbacks. Add the following code snippet at the start of the server section:

server <- function(input, output, session) {
  # Initialize Descope Auth
  session$sendCustomMessage("initDescopeAuth", list(
    projectId = "<YOUR_DESCOPE_PROJECT_ID>",
    flowId = "sign-up-or-in",
    theme = "light",
    containerId = "authContainer",
    successInput = "user_authenticated",
    errorInput = "auth_error"
  ))

  observeEvent(input$user_authenticated, {
    if (!is.null(input$user_authenticated)) {
      showNotification("Login successful!", type = "message")
      show("appContent")
    }
  })

  observeEvent(input$auth_error, {
    if (!is.null(input$auth_error)) {
      showNotification("Authentication failed. Please try again.", type = "error")
    }
  })
  ...
  # existing server definition
}

Replace YOUR_DESCOPE_PROJECT_ID with your Descope project ID, save the changes, and republish the app to Posit Connect using RStudio.

Test authentication using magic link

When a user clicks the magic link received in their email for authentication, Descope will validate the auth and redirect the user back to the Shiny application. For redirection to work, you need to configure the auth redirect URL in Descope. Head over to Magic link under Authentication Methods and set the Redirect URL to the published URL of your Shiny app.

To test the authentication, open the published content under the Content tab on Posit Connect.

When you run the app, you'll be redirected to the Descope auth screen. You can test the integration by entering your email ID on this screen and clicking the Continue button to log in with a magic link. You'll receive an email with a login link, and upon clicking it, you'll be redirected to the dashboard page of your Shiny app.

Create a new Descope tenant

After integrating vanilla authentication, the next step is to add SSO authentication using Descope. To do this, you first need to create a Tenant. Tenants represent organizations that use your application and make it easier to group and manage users, permissions, and authentication flows within the application. In this tutorial, you'll create a tenant for an example organization and use it to configure the SSO flow.

Navigate to Tenants and click the + Tenant button to create a new tenant.

Implement SSO with OIDC using Descope

OpenID Connect (OIDC) is an extension of the OAuth 2.0 authorization protocol that provides a standardized way for applications to request and receive identity information about users. Instead of managing user credentials for each application, OIDC SSO lets you delegate the authentication mechanism to a single trusted IdP, reducing the maintenance overhead. Once you log in, the IdP returns standardized JSON web tokens (JWTs) on login-containing information about the user's identity. In this section, you'll learn how to set up Descope as an OIDC IdP with Posit Connect.

Create a Descope OIDC application in a separate project

The Descope OIDC application acts as a federated IdP for the users. Based on your needs, Descope can act as a Service Provider (SP) or an IdP. An SP is an entity that initiates an authentication request to an IdP, which verifies the user's identity. After authentication, the SP processes the response from the IdP to determine whether the user should be granted access to the application. In the previous section, you configured the Descope project as an SP entity for auth and SSO.

You'll now create an OIDC application within Descope to turn it into an IdP, and subsequently, you'll also integrate it with your authentication flow. Since you're using Descope for both SP and IdP, to avoid cyclic dependency, both these entities should be configured in separate Descope projects.

First, use the Descope portal to create a new project to host the OIDC application. This tutorial sets the project name as descope-shiny-auth-sso.

You also need to create an OIDC application under the newly created project. Navigate to Applications and click the + Application button to register Generic OIDC Application.

Click Create to create the OIDC application and note the Descope OIDC endpoint configuration, as you'll need it while configuring the SSO tenant in the original project.

To configure OAuth with Posit Connect, you'll also need to create a new client secret. Navigate to the Access Keys page and click +Access key to create a new access key.

Configure Descope tenant to use OIDC SSO

To integrate the OIDC application with the authentication flow, you need to configure SSO under the example.com tenant you created under the original Descope SP project. A tenant lets you configure an authentication method using an OIDC or SAML application. This section discusses how to configure SSO using an OIDC application, and in a later section, you'll learn how to configure SSO using SAML.

Switch back to the Descope SP project and navigate to Tenants, and select the example.com tenant you created earlier. Choose Authentication Methods and select OIDC as the SSO authentication protocol. Make the following changes to configure SSO:

Under Tenant Details, add example.com to the SSO domains.
Update the SSO configuration by adding the following values:
- Provider name: Add a value for the provider. For example, the tutorial uses Descope as the provider name.
- Client ID: Use the Descope project ID for the descope-shiny-auth-sso project.
- Client Secret: Use the access key that you created above.
- Scopes: It sets the permissions for the access level that will be granted to the authenticated user. Add openid, profile, and email as the scopes.
- Issuer: Use the Issuer value from the OIDC application you created in the previous step.
- Authorization Endpoint: Use the Authorization URL value from the OIDC application.
- Token Endpoint: Use the Access Token URL value from the OIDC application.
- User Info Endpoint: Use the Access Token URL from the OIDC application by replacing /token with /userinfo.
Finally, Save the changes for them to take effect.

Configure SSO redirect URL

You also need to configure the Posit Connect application URL as an SSO redirect URL. Since the Shiny app is already configured to use Descope, it doesn't require any new changes. Grab the application URL, navigate to SSO under Authentication methods, and set it as the Redirect URL.

Note that the SSO redirect URL needs to be configured in the Descope SP project.

Test the OIDC SSO integration

Finally, to test the integration, open the application in the browser, enter your email ID, and click on Continue with SSO to initiate the SSO flow. Note that the email ID should use example.com for SSO to work since you didn't configure any other domains in Descope.

You'll be redirected to the IdP login screen, which, in this case, is hosted by the descope-shiny-auth-sso Descope project. You can verify this by comparing the project ID in the address bar with the Descope project ID.

For testing, complete the login using one of the social login options or the magic link, and upon authentication, you'll be redirected back to the Shiny dashboard.

Implement SAML SSO with Descope

SAML SSO is an XML-based open authentication standard that lets users log in to multiple web applications using a single set of credentials. SAML is a mature identity federation standard and is widely supported by legacy or internal enterprise applications. It serves a similar purpose to OIDC, but instead of JSON, it uses XML during authentication or authorization requests between the IdP and the SPs.

In this section, you'll learn how to configure SAML SSO with Descope using a mock SAML application and configuring the tenant to use SAML SSO.

Configure mock SAML tenant for testing

As you learned in the OIDC SSO section, Descope can act as both SP and IdP as needed, but this tutorial uses Descope as an SP and Mock SAML as an IdP. Mock SAML is a SAML 2.0 IdP that can test SAML SSO integrations quickly. If you don't have a SAML SP set up, you can use this tool to test your Descope SAML integration.

Navigate to Tenants and select the example.com tenant you created earlier. Choose Authentication Methods and change the SSO authentication protocol from OIDC to SAML. Make the following changes to configure SAML SSO:

Under Tenant Details, add example.com to the SSO domains.
Update the SSO configuration, select the Retrieve the connection details dynamically option, and set the Metadata URL for IdP to the following:

https://mocksaml.com/api/saml/metadata

Note: If you have a SAML SP setup, you can set the Descope Metadata (URL) of the SAML application instead of a Mock SAML URL.

Test the SAML SSO integration

To test the integration, open the application in the browser, enter your email ID, and click on Continue with SSO to initiate the SSO flow. Note that the email ID should use example.com for SSO to work since you didn't configure any other domains in Descope. If you used a mock URL, you'll be redirected to a MockSAML login page where you can confirm your email ID and click Sign in.

Note: If you configured a Descope SAML application with SP details, Descope will directly handle the authentication.

After logging in, you'll be redirected to the dashboard page.

Access users from Shiny

So you've now added authentication to the Shiny app using OIDC and SAML, but the Shiny application doesn't indicate that the user is logged in. This section discusses how to access the logged-in user metadata and display a welcome message in the UI.

You'll add a UI element to the sidebar and update the server definition to set the welcome message when the user is authenticated. First, add a welcomeText element to the sidebar by updating the sidebarPanel to the following:

sidebarPanel(
  # Add a welcome text element
  h3(textOutput("welcomeText")),
  br(),

  # Existing inputs
  fileInput("file", "Upload Expense Data (CSV)", accept = ".csv"),
  selectInput("category", "Select Category:", choices = NULL),
  actionButton("analyze", "Analyze"),
)

Update the user_authenticated observer under the server definition to set the welcome message:

observeEvent(input$user_authenticated, {
  req(input$user_authenticated)

  user_info <- input$user_authenticated

  # use "name", else fallback to "email", else "User"
  user_name <- user_info$name
  if (is.null(user_name)) user_name <- user_info$email
  if (is.null(user_name)) user_name <- "User"

  output$welcomeText <- renderText({
    paste("Welcome,", user_name)
  })

  showNotification("Login successful!", type = "message")
  show("appContent")
})

Notice that the above code snippet tries to retrieve the user's name from the user_info object and falls back to email if name is not present.

Save and republish the changes to test them. Once you log in to the dashboard, a welcome message will be displayed.

Log out a user

Your users also need logout functionality to enable them to end their sessions. To implement logout, first, add a logout button to the sidebar by updating the sidebarPanel as follows:

sidebarPanel(
  h3(textOutput("welcomeText")),
  br(),

  # Existing inputs
  fileInput("file", "Upload Expense Data (CSV)", accept = ".csv"),
  selectInput("category", "Select Category:", choices = NULL),
  actionButton("analyze", "Analyze"),

  # Logout button
  actionButton("logout", "Logout", icon = icon("sign-out-alt"))
)

Next, add a descopeLogout message handler in the descope-auth.js file that will be invoked when the logout button is clicked:

Shiny.addCustomMessageHandler('descopeLogout', function () {
  const wcElement = document.querySelector('descope-wc');
  if (wcElement) {
    wcElement.logout();
  }
});

Finally, add a logout observer under the server definition to invoke the descopeLogout and initDescopeAuth message handlers.

observeEvent(input$logout, {
  hide("appContent")  # Hide main content
  session$sendCustomMessage("descopeLogout", list())

  session$sendCustomMessage("initDescopeAuth", list(
    projectId = "P2pBl7sYVGg1RWtv4jC7zfO9TnUN",
    flowId = "sign-up-or-in",
    theme = "light",
    containerId = "authContainer",
    successInput = "user_authenticated",
    errorInput = "auth_error"
  ))
})

Save and republish the changes to test them. Once you log in to the dashboard, you'll notice a Logout button being displayed next to the Analyze button.

When you click the Logout button, you'll be logged out of the application and redirected to the Descope login page.

Make Shiny authentication simpler with Descope

Shiny makes it easier for data engineers and scientists to share their work with others as web applications without any HTML or JavaScript experience. Posit Connect is a publishing platform that lets you deploy Shiny apps directly from RStudio with a click of a button, eliminating the need to provision and maintain a web server.

In this article, you learned how to implement authentication and authorization in a Shiny app using Descope. You can find this tutorial's complete source code on GitHub.

Descope is a drag-and-drop customer authentication and identity management platform. Our low- or no-code CIAM solution helps hundreds of organizations easily create and customize their entire user journey using visual workflows—from authentication and authorization to MFA and federated SSO. Customers like Navan, GoFundMe, You.com, and Branch Insurance use Descope to reduce user friction, prevent account takeover, and get a unified view of their customer journey. To learn more, book a demo with our auth experts or join our dev community, AuthTown.

Add Authentication and SSO to Your Flet App

Mrunank Pawar — Fri, 24 Apr 2026 15:00:00 +0000

This blog was originally published on Descope.

Creating cross-platform applications has become much easier with frameworks like Flet. Flet allows developers to build modern web, desktop, and mobile apps using Python. Its simplicity and flexibility help developers focus on creating great user experiences without having to worry about platform-specific complexities.

However, as your application grows, so does the need to secure it. Adding secure authentication to your application helps to protect sensitive data by ensuring that only authorized users can access it. Descope is a modern authentication and user management platform that simplifies the integration of secure authentication features into your application. By providing out-of-the-box support for OAuth 2.0 and OpenID Connect (OIDC), Descope offers a reliable solution for implementing authentication in your Flet app.

In this guide, you will learn how to integrate Descope authentication and single sign-on (SSO) into a Flet application. You'll learn how to add basic authentication to your Flet app using Descope magic links and social login. You'll also configure Descope to use Okta as the identity provider (IdP), enabling SSO for your Flet app.

Why is adding SSO important for these types of apps?

SSO is essential for B2B applications that serve multiple companies. Each company may already use its own IdP—such as Okta, Google, or Azure—for authentication. By adding SSO, your application allows users to log in with existing credentials, which eliminates the need to create and manage separate accounts. This simplifies the onboarding process and enhances security by relying on trusted authentication providers.

SSO also improves the user experience by providing seamless access to different services within an organization. It allows employees to use their company credentials to log in, which reduces password fatigue and IT support overhead.

For businesses handling sensitive data, SSO ensures centralized access control, which makes it easier to enforce security policies while maintaining a smooth login process.

Prerequisites

To complete this tutorial, you need the following:

A Descope account
An Okta Developer account
Python 3 installed on your local machine
Git CLI installed on your local machine
A code editor and a web browser

Creating a Flet application

This tutorial uses a prebuilt starter template so you can focus on implementing authentication. To clone the starter template to your local machine, execute the following command:

git clone --single-branch -b starter-template https://github.com/kimanikevin254/descope-flet-auth-sso.git

cd into the project folder, set up a virtual environment, activate it, and install the project dependencies:

cd descope-flet-auth-sso

python3 -m venv venv

source venv/bin/activate

pip install -r requirements.txt

Here's an overview of the most important files in this project:

main.py: Sets up a simple Flet app with two views: a main view and a profile view. The MyApp class initializes the app, sets the page theme to light, and handles route changes and view pops. When the route changes (for example, when navigating to /profile), it updates the view accordingly, either showing the profile or the main view. It uses the AuthManager class to handle user authentication (login/logout). The route_handler method switches views based on the current route, and view_pop allows navigating backward through views. Finally, the run method starts the app with the main view.
auth/auth_helpers.py: Defines an AuthManager class that manages the auth-related functions. The handle_login method navigates the user to the /profile route while the handle_logout method navigates the user to the / route.
views/main_view.py: Displays a message with a login button that calls the handle_login method when clicked.
views/profile_view.py: Displays a message with a logout button that calls the handle_logout method when clicked.

You can run the application using the following command:

flet run -w --port 8550

This command opens the web version of the app. To view it, navigate to http://localhost:8550 on your browser, and you should see the demo application homepage with a Login button:

Click the Login button and you should be navigated to the profile page:

Right now, the profile page is accessible to anyone, which is not ideal. In the next section, you'll implement authentication to restrict access to authorized users.

Setting up Descope

To implement authentication in your Flet app, you first need to create a project and design a flow on your Descope console. To get started, launch your Descope console, click the project dropdown, and select + Project to create a new project:

On the Create project page, provide "descope-flet-auth-sso" as the project name and click Create to create the project:

The next step is to design a Descope flow. Flows define the authentication process. You're going to add support for three authentication methods: magic links, social login, and SSO. You need to design a flow that will support all the authentication methods.

Typically, you would need to design this flow from scratch, but to make it easy for you to follow along, this tutorial uses a pre-prepared flow, which is included in the starter template. You can find it in the project root folder in a file named sign-up-or-in.json. You just need to import this flow into the Descope console. To do this, navigate open the default sign-up-or-in flow in the flow editor by navigating to Flows > sign-up-or-in:

In the editor, select Import flow / Export flow > Import flow and upload the flow from your local machine:

The flow you imported presents three login methods on the welcome screen: magic link, SSO, and social login. If the user selects the magic link, an email is sent to the provided address. When the user clicks the link in the email, they are asked for additional details if they're a new user. If they're not new, the flow returns a JSON Web Token (JWT) and ends. For social login or SSO, the user is redirected to the appropriate provider. After successful authentication, they receive a JWT, and the flow ends.

Authentication with Descope

Now that you have implemented the authentication flow in the Descope console, you can go ahead and configure your Flet app to use Descope as an OAuth provider. Flet allows you to implement authentication with any identity provider that supports the OAuth 2.0 Authorization code flow. By default, Flet ships with a few built-in OAuth providers, such as Azure and Google, but it also allows you to configure a custom OAuth provider, like Descope.

To configure a custom OAuth provider, you need to configure the following in your Flet app:

Client ID: A public identifier for the application
Client secret: A secret that is only known to the application and the authorization server
Authorization endpoint: The endpoint that initializes the authorization flow
Token endpoint: The endpoint that exchanges an authorization code for access tokens
User endpoint: The endpoint that retrieves the authenticated user's information
Redirect URL: The URL where the user is redirected to after authentication
User ID function: A function that extracts the user ID from the returned user dictionary

To integrate Descope as the authentication provider for your Flet app, you first need to configure an OIDC app in the Descope dashboard to obtain the necessary endpoints required for the authorization code flow. To do this, navigate to Applications > OIDC default application on the Descope console:

Scroll down to the SP Configuration section and take note of the Client ID, Authorization URL, and Access Token URL. You will use these values in your Flet app.

For the user endpoint, you'll use https://api.descope.com/oauth2/v1/userinfo, which is discussed along with the other endpoints in the Descope documentation.

You also need to generate a client secret. You can do this by navigating to M2M > + Access Key. On the Generate Access Key form, provide the key name, select Generate Key, and copy the value of your key.

Now that you have these values, you can go back to your Flet app and start implementing authentication. First, create a new file named .env in the project root folder and add the following code:

OAUTH_CLIENT_ID="<YOUR-DESCOPE-CLIENT-ID>"
OAUTH_CLIENT_SECRET="<YOUR-DESCOPE-CLIENT-SECRET>"
OAUTH_AUTHORIZATION_ENDPOINT="https://api.descope.com/oauth2/v1/authorize"
OAUTH_TOKEN_ENDPOINT="https://api.descope.com/oauth2/v1/token"
OAUTH_USER_ENDPOINT="https://api.descope.com/oauth2/v1/userinfo"
OAUTH_REDIRECT_URI="http://localhost:8550/oauth_callback"
OAUTH_USER_ID_FIELD="sub"
OAUTH_SCOPES="openid profile email"

Some of the values have been prefilled for you as they will be the same for everyone. However, the client ID and client secret will be unique to you. Make sure you replace the placeholder values with the values you obtained from the Descope console.

You also need a utility file to extract the environment variables and make them available for use in different parts of the application. Create a new file named config.py in the project root folder and add the following code:

from dotenv import load_dotenv
import os

load_dotenv()

class Config:
    @staticmethod
    def get_env_var(name, default=None, required=True):
        value = os.getenv(name, default)
        if required and value is None:
            raise ValueError(f"Environment variable '{name}' is required but not set.")
        return value

    OAUTH_CLIENT_ID = get_env_var('OAUTH_CLIENT_ID')
    OAUTH_CLIENT_SECRET = get_env_var('OAUTH_CLIENT_SECRET')
    OAUTH_AUTHORIZATION_ENDPOINT = get_env_var('OAUTH_AUTHORIZATION_ENDPOINT')
    OAUTH_TOKEN_ENDPOINT = get_env_var('OAUTH_TOKEN_ENDPOINT')
    OAUTH_USER_ENDPOINT = get_env_var('OAUTH_USER_ENDPOINT')
    OAUTH_REDIRECT_URI = get_env_var('OAUTH_REDIRECT_URI')
    OAUTH_USER_ID_FIELD = get_env_var('OAUTH_USER_ID_FIELD')
    OAUTH_SCOPES = get_env_var('OAUTH_SCOPES')

This code loads environment variables from a .env file and defines a Config class with a method to retrieve them, raising an error if a required variable is missing. It then uses this method to set various OAuth-related settings as class attributes.

To define a custom OAuth provider, create a new file named auth_provider.py in the auth folder and add the code below:

from flet.auth import OAuthProvider as BaseOAuthProvider
from config import Config

class OAuthProvider(BaseOAuthProvider):
    def __init__(self):
        super().__init__(
            client_id=Config.OAUTH_CLIENT_ID,
            client_secret=Config.OAUTH_CLIENT_SECRET,
            authorization_endpoint=Config.OAUTH_AUTHORIZATION_ENDPOINT,
            token_endpoint=Config.OAUTH_TOKEN_ENDPOINT,
            user_endpoint=Config.OAUTH_USER_ENDPOINT,
            redirect_url=Config.OAUTH_REDIRECT_URI,
            user_id_fn=lambda u: u[Config.OAUTH_USER_ID_FIELD],
        )

This code defines an OAuthProvider class that inherits from the Flet OAuthProvider class and initializes it with OAuth configuration settings from the Config class.

Open the auth/auth_helpers.py file. Here, you will modify the methods to log in and log out the user instead of just navigating them. First, replace the import statements with the following:

from flet import Page, LoginEvent
from config import Config

Then, replace the handle_login method with the following to trigger the login process using the OAuth provider configured for the page:

def handle_login(self, e):
    self.page.login(self.page.oauth_provider)

Replace the handle_logout method with the following to log the user out by calling the logout function on the page:

def handle_logout(self, e):
    self.page.logout()

In the same class, add the following methods to configure methods that will be called when the user is successfully logged in or out:

def on_login(self, e: LoginEvent):
    if e.error:
        raise Exception(e.error)

    self.page.go('/profile')

def on_logout(self, e):
    self.page.go('/')

These methods handle login and logout events: on_login checks for errors during login and navigates to the /profile route if successful, while on_logout redirects the user to the home route (/).

Open the views/profile_view.py file and replace the get_view method with the following:

def get_view(self):
    return ft.View(
        route='/profile',
        vertical_alignment=ft.MainAxisAlignment.CENTER,
        horizontal_alignment=ft.CrossAxisAlignment.CENTER,
        controls=[
            ft.Column(
                alignment=ft.MainAxisAlignment.CENTER,
                horizontal_alignment=ft.CrossAxisAlignment.CENTER,
                controls=[
                    ft.CircleAvatar(
                        foreground_image_src=self.page.auth.user.get("picture", ""),
                        bgcolor=ft.Colors.GREY_400,
                        radius=40
                    ),
                    ft.Text(value=self.page.auth.user.get("name", "N/A"), size=20, weight=ft.FontWeight.BOLD),
                    ft.Text(value=self.page.auth.user.get("email", "N/A"), size=18),
                    ft.ElevatedButton(text="Logout", on_click=self.handle_logout),
                ],
            )
        ]
    )

This method returns a view for the profile page that displays the authenticated user's profile picture, name, and email in the center of the page, along with a Logout button.

Open the main.py file and add the following import statement:

from auth.auth_provider import OAuthProvider

Add the following line of code to the __init__ method just before self.auth_manager = AuthManager(page=self.page) to create an instance of the OAuth provider and attach it to the current page:

self.page.oauth_provider = OAuthProvider()

Register the event handler you created earlier to the page by adding the following code at the end of the __init__ method:

self.page.on_login = self.auth_manager.on_login
self.page.on_logout = self.auth_manager.on_logout

Finally, you need to protect the /profile page to make sure it cannot be accessed by unauthenticated users. To do this, in the route_handler method, replace the first block of the if statement with the following:

if self.page.route == '/profile':
    if(self.page.auth is None):
        return self.page.go(route='/')
    view = ProfileView(self.page, self.auth_manager.handle_logout)
    self.page.views.append(view.get_view())

This code checks if the current route is /profile; if the user isn't authenticated, it redirects them to the home page. Otherwise, it loads the ProfileView and appends it to the page.

At this point, you should be able to log in to the application using either magic links or social login. In the next section, you will implement SSO.

Implement SSO with OIDC using Descope

OIDC is a simple identity layer built on top of OAuth 2.0. It helps enable SSO by allowing users to authenticate through trusted IdPs, such as Azure or Okta. With Descope, you can easily integrate OIDC SSO into your app, letting users log in securely with their existing credentials, which streamlines access without the need for new accounts.

In this section, you'll implement SSO by configuring Okta as the IdP and Descope as the authentication service. To do this, open your Okta admin dashboard and navigate to Applications > Applications > Browse App Catalog:

On the Browse App Integration Catalog page, search for "descope" and select the Descope app:

On the app details page, select Add Integration:

On the Add Descope page under General Settings, leave the default settings and click Next:

On the Sign-On Options page, select OpenID Connect as the sign-on method, and under Advanced Sign-on Settings, in the Callback URL field, provide the value https://api.descope.com/v1/oauth/callback. This is where the user will be redirected after successful authentication by Okta.

Scroll down to the bottom of the page and click Done.

On the app details page, select the Sign On tab and take note of the client ID and secret.

You'll also need a tenant to use SSO. Back on your Descope console, navigate to Tenants > + Tenant. On the Create Tenant form, provide the tenant name and click Create:

Open the details page of the tenant you just created and under Tenant Settings. Make sure you add your email domain to the list of allowed domains and click Save:

Next, still on the tenant details page, select Authentication Methods > SSO > OIDC. Under Tenant Details > SSO Domains, make sure to provide your email domain. This domain is used to determine which SSO configuration to load once a user chooses to authenticate using SSO.

Scroll down to the SSO configuration > Account Settings section and provide the required values as follows:

Provider Name: Okta
Client ID: The Client ID you obtained from the Okta dashboard
Client Secret: The client secret you obtained from the Okta dashboard
Scope: openid profile email
Grant Type: Authorization code

You also need to provide the required values for the SSO configuration > Connection Settings section. For this, you need to obtain OAuth endpoints from the Okta "well-known" configuration, which provides standardized metadata for OAuth and OIDC integrations. To obtain this, navigate to https://<YOUR-OKTA-INSTANCE>.okta.com/.well-known/openid-configuration on your browser and take note of the issuer and authorization, token, user info, and JWKs endpoints.

Make sure to replace <YOUR-OKTA-INSTANCE> with the correct value, which is your organization's Okta instance ID.

Go back to the Descope console and provide the values you just obtained from the Okta well-known endpoint in the respective inputs under SSO configuration > Connection Settings and save the changes.

To ensure that only authorized users can authenticate via the app and access your Flet application, you assign users to the Descope app you installed in your Okta console. To do this, open the app details page in Okta and select Assignments > Assign > Assign to Groups:

On the Assign Descope Groups page, select the Assign button beside the Everyone group to allow all users in your organization to log in via SSO and click Done to save the changes.

SSO with Okta as the IdP is now fully configured.

Adding a persistent login feature

Currently, the app does not save the access token obtained from Descope. So if a user logs in, leaves the app, and then returns, they will need to log in again. To improve the user experience, you can add a function that saves the access token to client storage.

However, you cannot store the token in client storage as plain text as this would make it vulnerable to malicious actors who could access and manipulate it. Instead, you need to encrypt the token using a secret key and save the encrypted value securely.

Open the .env file in the project root folder and add the following:

OAUTH_TOKEN_SECRET="cv3Gc9RG-9o8icwTBUEDb0HJC7M5A0b2FxT3WpWvg1I="
OAUTH_TOKEN_KEY="auth_token"

Values for these variables have been provided, but you can change them to any string.

OAUTH_TOKEN_SECRET will be used to encrypt the access token before saving it to the client storage, while OAUTH_TOKEN_KEY is the key under which the encrypted token will be saved in the client storage.

To load the environment variables you just created into the Flet application, open the config.py file and add the following attributes to the Config class:

OAUTH_TOKEN_SECRET = get_env_var('OAUTH_TOKEN_SECRET')
OAUTH_TOKEN_KEY = get_env_var('OAUTH_TOKEN_KEY')

Open the auth/auth_helpers.py file and add the following import statements:

from flet.security import encrypt, decrypt

encrypt and decrypt are utility methods provided by Flet for encrypting text data using a symmetric algorithm. This means that the same key is used for encryption and decryption.

Replace the on_login method with the following to modify the on_login method to encrypt and save the token to client storage once a user is successfully authenticated:

def on_login(self, e: LoginEvent):
    if e.error:
        raise Exception(e.error)

    # Save token in client storage
    token = self.page.auth.token.to_json()
    encrypted_token = encrypt(token, Config.OAUTH_TOKEN_SECRET)
    self.page.client_storage.set(Config.OAUTH_TOKEN_KEY, encrypted_token)

    self.page.go('/profile')

This code retrieves the access token, encrypts it using the secret key you set earlier, and stores the encrypted token in client storage. It then redirects the user to the profile page.

Replace the handle_login method with the following to modify the handle_login method to check if a valid token is stored in the client storage before redirecting the user to the sign-in page:

def handle_login(self, e):
    saved_token = None

    # Retrieve token from client storage
    encrypted_token = self.page.client_storage.get(Config.OAUTH_TOKEN_KEY)

    # Decrypt retrieved token
    if encrypted_token:
        saved_token = decrypt(encrypted_data=encrypted_token, secret_key=Config.OAUTH_TOKEN_SECRET)

    # Log in the user
    if e is not None or saved_token is not None:
        self.page.login(provider=self.page.oauth_provider, saved_token=saved_token, scope=Config.OAUTH_SCOPES.split())

This code retrieves the saved encrypted token from the client storage, decrypts it, and passes it to the self.page.login method. This way, if the token is valid, the application will obtain the user's info without prompting the user to reauthenticate.

Lastly, replace the handle_logout method with the following to modify the handle_logout method to make sure that it removes the token from storage when a user logs out:

def handle_logout(self, e):
    self.page.client_storage.remove(Config.OAUTH_TOKEN_KEY)
    self.page.logout()

Persistent login should now be working as expected.

Demonstrating the application

You can run the application to confirm that everything is working as expected.

Run the application using the command flet run -w --port 8550, navigate to http://localhost:8550 on your browser, and click the Login button. You should be redirected to the sign-in page:

Here, you can choose to sign in with any method, and after successful authentication, you will be redirected to the profile page, where your details are displayed:

You can stop the application and run it again. Then, on the home route, click the Login button. You will be redirected to the profile page without being prompted to sign in again.

You can access the full code on GitHub.

Conclusion

Implementing authentication and SSO into your Flet app using Descope is a straightforward process that significantly enhances your application's security and user experience. By integrating features like magic link authentication, social logins, and SSO with OIDC, you can offer your users seamless and secure access, whether they are individuals or part of an organization using their existing credentials.

Descope is a drag-and-drop customer authentication and identity management platform. Our no- or low-code CIAM solution helps hundreds of organizations easily create and customize their entire user journey using visual workflows—from authentication and authorization to MFA and federated SSO. Customers such as GoFundMe, Navan, You.com, and Branch use Descope to reduce user friction, prevent account takeover, and get a unified view of their customer journey. To learn more, join our dev community, AuthTown, and explore the Descope documentation.

Add Authentication and SSO to Your Panel App

Mrunank Pawar — Wed, 22 Apr 2026 15:00:00 +0000

This blog was originally published on Descope.

Panel is an open source Python library for creating interactive data visualization applications. As these applications grow, secure authentication becomes essential to protect the data, ensure compliance with security standards, and deliver a seamless user experience. Descope, a no-/low-code customer identity and access management (CIAM) platform, simplifies authentication by offering ready-to-use solutions for secure login, single sign-on (SSO), and user access control. Its support for OpenID Connect (OIDC), a widely adopted standard for secure and scalable user authentication, makes it an excellent choice for securing Panel apps, allowing developers to focus on building core features while relying on a trusted platform for authentication.

In this tutorial, you'll learn how to integrate Descope into your Panel application by implementing secure user authentication, configuring access control, and providing a seamless SSO experience for your users. You will start by adding vanilla authentication with Descope via magic links, add support for social login, and lastly, implement SSO with Okta as the identity provider (IdP).

Why is adding SSO important for these types of apps?

SSO is often added to data visualization tools because these tools are typically designed for B2B use. Here are some of the advantages of integrating SSO into a data visualization tool:

Simplifying access for end users: B2B applications frequently cater to multiple companies with their own employees and systems. Each of these companies will have an IdP—such as Okta, Azure AD, or Google Workspace—which they use for secure access to tools and resources. Integrating SSO into your application allows users to sign in with their existing corporate accounts, which eliminates the need for another set of credentials.

Strengthening security and compliance: SSO ensures that authentication is handled through the organization's IdP, which is often configured with advanced security features like MFA and conditional access policies. This reduces the risk of unauthorized access and strengthens compliance with industry standards such as GDPR and HIPAA, which are crucial for data-driven applications.

Simplified management for developers: From a developer's perspective, SSO integration reduces the complexity of user account management. With SSO, developers can offload the responsibility of managing user credentials and access roles to the IdP, which not only saves time but also reduces the risk of mishandling sensitive user information.

Adding SSO to your application improves the user experience and future-proofs it to meet the needs of enterprise customers while maintaining high security standards.

Prerequisites

To follow along with this guide, you need to have the following:

A Descope account
An Okta developer account
Python 3 installed on your local machine
Git CLI installed on your local machine
A code editor and a web browser

Creating a Panel app

For simplicity, this tutorial uses a prebuilt application that you add authentication to. To clone the application to your local machine, launch your terminal and execute the following command:

git clone --single-branch -b starter-template https://github.com/kimanikevin254/descope-panel-auth-sso.git

Create and activate a virtual environment for your application to run in:

cd descope-panel-auth-sso

python -m venv venv

source venv/bin/activate

Next, install all the dependencies using the command below:

pip install -r requirements.txt

The application is now set up. The two most important files in the application are admin.py and user.py. admin.py is used to set up an admin dashboard for a Panel application and will only be accessed by users with the appropriate roles after you have implemented auth and role-based access control. user.py sets up a Panel app that allows users to interact with a data set and view rolling averages and outliers for different variables. You can learn more about this application in the Panel docs.

Run the application using the following command:

panel serve admin.py user.py --dev

Launch your browser and navigate to http://localhost:5006/. You'll see that you have two Panel apps running:

At the moment, you can open any application. However, later on, you will implement authorization to ensure that the "Admin" application can only be accessed by users with the appropriate roles.

Setting up Descope

Here, you will create a project on your Descope console and implement an authentication flow to set up your application's authentication process. This flow will enable your users to authenticate using any of the three methods we discussed: magic links, social logins, and SSO.

To get started, launch your Descope console and select + Project from the project dropdown to create a new project:

In the Create project modal, provide descope-panel-auth-sso as the project name and click Create to create the project:

To create an authentication flow, select Flows > sign-up-or-in on the Descope console to open the default sign-up-or-in flow in the flow editor:

As mentioned earlier, you're going to customize this flow to support three different authentication methods: magic links, social logins, and SSO login. This tutorial uses an already-prepared flow that you just need to import.

The project you set up earlier contains a file named sign-up-or-in.json, which is where you'll find the flow logic. You can import it into the flow editor by selecting Import flow / Export flow > Import flow inside the editor and uploading the flow from your local machine:

The flow you just imported should now have all the authentication methods that you need:

Magic links and social login authentication methods are now fully configured. You will configure SSO later.

Adding authentication with Descope

In this section, you'll configure Descope as a generic OAuth provider for your Panel application.

Panel performs authentication through OAuth 2.0, a widely used protocol that delegates authentication to third-party providers, such as Google and GitHub. By default, Panel ships with support for various OAuth providers, but it also allows you to configure authentication via any Generic OAuth provider that has configurable endpoints, such as Descope.

To set up authentication with Descope, you need to configure specific settings. These can be passed through environment variables or via CLI arguments when you're running the application. In this guide, we will use environment variables for simplicity.

Here are the required environment variables:

PANEL_OAUTH_KEY: A public identifier for the application
PANEL_OAUTH_SECRET: A secret that is only known to the application and the authorization server
PANEL_OAUTH_AUTHORIZE_URL: The endpoint that initializes the authorization flow
PANEL_OAUTH_TOKEN_URL: The endpoint that exchanges an authorization code for access tokens
PANEL_OAUTH_USER_URL: The endpoint that retrieves the authenticated user's information
PANEL_COOKIE_SECRET: A random, unguessable string for encrypting cookies
PANEL_OAUTH_REDIRECT_URI: The URL where the user is redirected to after authentication
PANEL_OAUTH_ENCRYPTION: For encrypting user information and access tokens
PANEL_OAUTH_SCOPE: Defines the scope of permissions requested from the authorization server

You will obtain some values for these environment variables from the Descope console and generate others on the terminal.

Create a new file named .env in the project root folder and add the content below. You will assign values for each environment variable as you proceed.

PANEL_COOKIE_SECRET=
PANEL_OAUTH_REDIRECT_URI="http://localhost:5006"
PANEL_OAUTH_ENCRYPTION=
PANEL_OAUTH_SCOPE=
PANEL_OAUTH_KEY=
PANEL_OAUTH_SECRET=
PANEL_OAUTH_AUTHORIZE_URL=
PANEL_OAUTH_TOKEN_URL=
PANEL_OAUTH_USER_URL=

To integrate Descope as your authentication provider, you first need to configure an OIDC app in the Descope dashboard. This configuration provides the necessary endpoints and credentials for your Panel application. You could choose to create a new OIDC application for this integration, but in this example, you can simply use the default OIDC application that ships with Descope. Access the application by navigating to Applications > OIDC default application on the Descope console:

In the OIDC app's details page, scroll down to the SP Configuration section, take note of the Client ID, Authorization URL, and Access Token URL, and assign them to the PANEL_OAUTH_KEY, PANEL_OAUTH_AUTHORIZE_URL, and PANEL_OAUTH_TOKEN_URL environment variables in the .env file, respectively.

For the PANEL_OAUTH_USER_URL environment variable, assign the value https://api.descope.com/oauth2/v1/userinfo.

For the PANEL_OAUTH_SCOPE environment variable, provide the value openid email profile descope.claims descope.custom_claims. The openid email profile scopes request basic user information, while the descope.claims descope.custom_claims scopes request the user roles, permissions, tenants, and custom claims from the IdP. However, for the descope.claims descope.custom_claims scopes to be provided, you need to go back to your OIDC application and add them to the Supported Claims list under IdP Configuration:

Remember to save the changes.

To obtain the value for the PANEL_OAUTH_SECRET environment variable, create an access key by navigating to M2M > + Access Key on the Descope console. Name the key whatever you like and click Generate Key:

Copy the value of the generated key, and assign it to the PANEL_OAUTH_SECRET environment variable in the .env file.

Make sure your virtual environment is activated, and then execute the following command in your terminal to generate a value for the PANEL_COOKIE_SECRET environment variable:

panel secret

Lastly, activate the Python shell by executing the command python in your terminal, and execute the following code to generate a value for the PANEL_OAUTH_ENCRYPTION environment variable:

from cryptography.fernet import Fernet

key = Fernet.generate_key()
print(key.decode())

Now Descope is fully configured as a generic OAuth provider for Descope. At this point, you can run the application using the command panel serve admin.py user.py --oauth-provider=generic --dev and test if authentication is working as expected.

Keep in mind that only magic links and social login authentication methods should be working at this point. You will work on SSO in the next section.

Implement SSO with OAuth using Descope

OAuth 2.0 is an industry-standard protocol for authorization that enables applications to securely access user resources without requiring them to share their credentials. OAuth acts as a "middleman" that allows users to grant limited access to their information stored on an IdP to the Service Provider (SP), such as your application. When combined with OIDC, which is built on top of OAuth, this protocol also enables SSO, which allows users to log in once with their existing credentials and gain access to multiple applications or systems without having to log in again.

In this section, you'll configure Okta as the IdP and Descope as the OAuth service to integrate authentication and SSO into your Panel application.

To get started, go to your Okta admin dashboard and navigate to Applications > Applications > Browse App Catalog:

On the Browse App Integration Catalog page, search for "Descope" and select the Descope application:

Next, on the application details page, select + Add Integration:

On the Add Descope page, under General Settings, provide Descope Panel Auth and SSO as the Application label and click Next:

On the Sign-On Options page, select OpenID Connect as the sign-on method, and under Advanced Sign-on Settings, in the Callback URL field, provide the value https://api.descope.com/v1/oauth/callback. This is the URL the user will be redirected to after successful authentication by the IdP.

Scroll down to the bottom of the page and select Done.

On the app details page, select the Sign On tab and take note of your client ID and client secret:

Head back to the Descope console and select Tenants > + Tenant to create a new tenant. On the Create Tenant modal, provide Descope Panel Auth and SSO as the tenant name and click Create:

Open the tenant details page, and under Tenant Settings, add your email domain to the list of allowed domains and save the changes:

Still on the tenant details page, navigate to Authentication Methods > SSO and select OIDC. Under Tenant Details, add your email domain, which will help to determine the SSO configuration to load when a user chooses to authenticate with SSO:

Scroll down to the SSO configuration > Account Settings section and provide the required values as follows:

Provider Name: Okta
Client ID: The Client ID you obtained from the Okta dashboard
Client Secret: The client secret you obtained from the Okta dashboard
Scope: openid profile email
Grant Type: Authorization code

You also need to provide the values for the SSO configuration > Connection Settings section. For these, you'll need to obtain OAuth endpoints from the Okta "well-known" configuration. To obtain this, navigate to https://<YOUR-OKTA-INSTANCE>.okta.com/.well-known/openid-configuration on your browser and take note of the issuer and authorization, token, user info, and JWKS endpoints.

Make sure to replace <YOUR-OKTA-INSTANCE> with the correct value, which is your organization's Okta instance ID.

Head back to the Descope console, input these values in their respective endpoints under SSO configuration > Connection Settings, and save the changes.

Under SSO Mapping > User Attribute Mapping, you can choose to configure how attributes from Okta will be mapped to Descope, but we will not be doing so in this guide. The default mapping is sufficient for this example. For more information on how to add custom claims to your Okta OIDC tokens, check out the official docs.

You also need to assign users to the Descope app in Okta to grant them access. This step ensures that only authorized users can authenticate via the app and access your Panel application. To do this, open the app details page in Okta and select the Assignments > Assign > Assign to Groups:

On the Assign Descope Panel Auth and SSO to Groups page, select the Assign button beside the Everyone group to allow all users in your organization to log in via SSO and click Done to save the changes.

Add authorization

Authorization allows your app to determine what actions an authenticated user can perform and the data they can access. For example, in your Panel application, administrators might have access to advanced analytics and management tools, while regular users can only view specific dashboards.

At the moment, any user can access any dashboard in your application. Let's limit what dashboard a user can access based on their roles.

To do this, create a new file named main.py in the root project folder and add the following code, which retrieves user roles and redirects them to the appropriate dashboard:

from dotenv import load_dotenv
import os
import panel as pn

# Load env variables
load_dotenv()

# Enable Panel extension
pn.extension(sizing_mode="stretch_width")

# Define the authorization callback
def authorize(user_info):
    """
    Authorization callback to redirect users based on roles.
    """
    # Extract user roles from the user_info dict
    roles = user_info.get('tenants', {}).get(os.getenv('DESCOPE_TENANT_ID'), {}).get('roles', [])

    if "Tenant Admin" in roles:
        return "/admin"
    else:
        return "/user"

# Assign the authorization callback
pn.config.authorize_callback = authorize

The authorize function checks the user's roles from the user_info dictionary, which includes details about their roles in a specified tenant (retrieved from an environment variable). Depending on whether the user has the Tenant Admin role, they are redirected to either the admin dashboard (/admin) or the user dashboard (/user).

You'll also need to protect the admin dashboard so that users don't try to manually navigate to the /admin endpoint on their browser. To do this, Open the admin.py file and replace the existing code with the following:

from dotenv import load_dotenv
import os
import panel as pn

load_dotenv()

# Enable Panel extension
pn.extension(sizing_mode="stretch_width")

# Extract roles and permissions
tenant_data = pn.state.user_info.get('tenants', {}).get(os.getenv('DESCOPE_TENANT_ID'), {})
roles = tenant_data.get('roles', [])
permissions = tenant_data.get('permissions', [])

# Admin dashboard content
admin_content = f"""
# You're an admin. You have access to more data and functionality.

#### Your Roles:
<ul>
    {"".join(f"<li>{role}</li>" for role in roles) if roles else "<li>No roles assigned</li>"}
</ul>

#### Your Permissions:
<ul>
    {"".join(f"<li>{permission}</li>" for permission in permissions) if permissions else "<li>No permissions assigned</li>"}
</ul>
"""

# Authorization callback for the admin dashboard
def authorize_admin(user_info):

    if "Tenant Admin" in roles:
        return True
    return "/user"

# Assign the authorization callback
pn.config.authorize_callback = authorize_admin

# Create and configure the Material template
template = pn.template.MaterialTemplate(
    site="Panel",
    title="Admin Dashboard",
    main=[admin_content]
)

# Serve the admin dashboard
template.servable()

This code sets up the admin dashboard where the user roles and permissions are displayed and also checks if the user has the Tenant Admin role. If not, they are redirected to the user dashboard.

Open the .env file in the project root folder and add the following content, replacing the placeholder value with the ID of the tenant you created earlier on the Descope console:

DESCOPE_TENANT_ID="<YOUR-DESCOPE-TENANT-ID>"

At this point, if you run the application using the command panel serve admin.py user.py --oauth-provider=generic --dev and authenticate successfully, you'll be redirected to the default Panel landing page, which lists all the running applications. You need to add a function that automatically redirects the user to the appropriate app. To do this, create a new file named index.html in the project root folder and add the following code:

<!DOCTYPE html>
<html lang="en">
    <head>
        <meta http-equiv="Refresh" content="0; url='/main" />
    </head>
    <body>
        <p>Redirecting...</p>
    </body>
</html>

This HTML file acts as a redirect page for your Panel application. After successful authentication, users are redirected to http://localhost:5006, where this file automatically navigates them to the /main route. The /main route loads the main.py file, which determines whether users should be redirected to the admin or user dashboard based on their roles.

Refreshing the access tokens

In Panel, access tokens are cached as cookies. Depending on the OAuth provider you're using, these tokens may eventually expire. For example, Okta access tokens expire after thirty days. This means a user might remain logged into your application even though their access token has expired since it is cached.

To ensure you always have access to a valid access token, open the .env file in the project root folder and add the following line:

PANEL_OAUTH_REFRESH_TOKENS=1

This ensures that if a user tries to access your application with an expired token, the application will automatically fetch a new access token using the saved refresh token. If no refresh token is available, the user will be prompted to reauthenticate. As long as the user's session is active, the application will also schedule token refreshes ten seconds before the access token expires.

Adding a logout feature

Allowing users to log in to your Panel application is as simple as adding a widget and configuring the widget to redirect the user to the /logout endpoint.

First, open the admin.py and add the following code below the admin_content variable:

# Logout button
logout_widget = pn.widgets.Button(name="Logout", button_type="danger", width=100, align="end")

# Configure logout functionality
logout_widget.js_on_click(code="""window.location.href = '/logout'""")

This code creates a Logout button that redirects the user to the /logout URL when clicked.

Add this button to the dashboard's header by replacing the code that creates the Material template with the following:

template = pn.template.MaterialTemplate(
    site="Panel",
    title="Admin Dashboard",
    header=[pn.Row(pn.layout.Spacer(), logout_widget)],
    main=[admin_content]
)

You also need to do the same to the user.py file. Open the file and add the following code below signma_widget = pn.widgets.Button(...):

# Logout button
logout_widget = pn.widgets.Button(name="Logout", button_type="danger", width=100, align="end")

# Configure logout functionality
logout_widget.js_on_click(code="""window.location.href = '/logout'""")

Lastly, modify the code that creates the Material template, like this:

# Configure the template with the logout button in the header
template = pn.template.MaterialTemplate(
    site="Panel",
    title="User Dashboard",
    header=[pn.Row(pn.layout.Spacer(), logout_widget)],
    sidebar=[variable_widget, window_widget, sigma_widget],
    main=[bound_plot]
)

Testing the application

Now that everything is fully configured, you can test the application. To do this, make sure your virtual environment is still active and execute the following command in the terminal:

panel serve main.py admin.py user.py --oauth-provider=generic --index index.html --dev

Navigate to http://localhost:5006 on your browser, and you should be navigated to a sign-in page that is powered by the Descope flow you configured earlier:

On this page, you can choose to authenticate using any method. After successful authentication, you will be redirected to the user dashboard:

This shows that the authorization callback is working as expected as the user was not redirected to the admin dashboard.

Sign out of the app by clicking the Logout button. Go to the Descope console and navigate to the Users page. Here, identify the user you just signed in with, assign them the Tenant Admin role, and save the changes:

Go back to http://localhost:5006 on your browser and sign in again with the same credentials, and you'll now have access to the admin dashboard:

Conclusion

In this guide, you learned how to integrate secure authentication and SSO into a Panel application using Descope. From implementing secure authentication flows on the Descope console to integrating Okta as an IdP and implementing role-based access control, you now have the essential skills to enhance both security and user experience in your Panel apps. As a next step, you can explore additional features like multifactor authentication (MFA) and support for multiple SSO providers.

Descope is a drag-and-drop customer authentication and identity management platform. Our no-/low-code CIAM solution helps hundreds of organizations easily create and customize their entire user journey using visual workflows—from authentication and authorization to MFA and federated SSO. Customers like GoFundMe, Navan, You.com, and Branch use Descope to reduce user friction, prevent account takeover, and get a unified view of their customer journey. To learn more, join our dev community, AuthTown, and explore the Descope documentation.

Next.js 15 vs. Next.js 16: What's the Difference?

Mrunank Pawar — Mon, 20 Apr 2026 15:00:00 +0000

This blog was originally published on Descope.

Next.js 16 marks a significant shift for the framework. What started as a simple SSR helper is now a comprehensive full-stack React engine.

This release brings major changes: Turbopack replaces Webpack as the default bundler, Cache Components introduces Partial Pre-Rendering (PPR), and middleware.ts becomes proxy.ts. The performance improvements are substantial, but you still may not be ready to switch over. You might be concerned about bugs, don't have time for migration work, or simply aren't ready to abandon Webpack yet.

This article breaks down what's actually different between Next.js 15 and 16, so you can decide whether to upgrade now or wait until v15's LTS support expires. If you do decide to switch over, we've included a short migration guide at the end to help ease your transition.

Next.js 15 vs. 16 at a glance

Feature	Next.js 15	Next.js 16
Bundler	Webpack as the default bundler, with Turbopack as an optional/experimental alternative.	Turbopack replaces Webpack, offering up to 10× faster Fast Refresh and 5× faster builds.
Caching Model	Fetch requests are cached by default with limited Partial Pre‑Rendering (PPR).	Cache Components with Partial Pre‑Rendering (PPR) for instant navigation and predictable caching defaults.
Middleware Architecture	Middleware API for routing and edge logic.	Middleware replaced by proxy.ts for clearer network boundaries.
React Version & Compiler	Introduced React 19 support along with the Speedy Web Compiler (SWC) for transpilation.	Offers full React 19.2 support and uses SWC with Turbopack integration for faster builds.
Image Optimization	Next.js Image component with built‑in optimization (WebP, AVIF).	Continued Image optimization and tighter integration with Turbopack for faster builds.
AMP Support Status	AMP is deprecated, but legacy support is still available.	AMP is fully deprecated and no longer supported in v16.

Performance and bundling

When deciding whether you should move from Next.js 15 to 16, performance is often the most important consideration.

The bundler plays a big role in the framework's performance. Next.js has used Webpack as the default bundler since the first version of the framework was released in 2016. Vercel's full move to Turbopack is one of the reasons Next.js 16 was such a pivotal release.

Next.js 15: Webpack default, Turbopack opt-in

As with the three previous iterations (v14, v13, and v12), Next.js 15 uses version 5 of Webpack. It offered improved disk caching, optimized Fast Refresh, more stable long-term caching of assets, and enhanced tree shaking over its predecessors.

In addition to the default implementation of WebPack, Next.js 15 also allowed developers to opt into an alpha version of Turbopack (using the --turbopack flag), a feature that had been present since Next.js 13. This inclusion allowed developers to experiment with and acclimate themselves to the bundler. It also allowed them to influence development by testing, reporting bugs, and sharing their ideas on how it could be improved.

Despite being in alpha, Turbopack was already showcasing boosts in build speed and hot reload times compared to Webpack; improvements that stemmed from its rewrite in Rust.

Next.js 16: Turbopack as default bundler

Next.js 16 fully replaced Webpack with Turbopack, much to the chagrin of developers who had an affinity for Webpack and disliked the fact that everything was being rewritten in Rust. However, Turbopack's use of Rust is precisely why it can outperform its JavaScript-based predecessor so easily.

Turbopack uses Rust's low-level control, fearless concurrency, and persistent caching to deliver incremental bundling where only changed files are rebuilt as opposed to the entire dependency graph. This also makes Hot Module Replacement (HMR) more efficient, since faster builds allow HMR to inject updated modules into the browser runtime more quickly.

Since Rust avoids unpredictable pauses (like garbage collection in JavaScript), it allows for incremental updates to be applied consistently and quickly, which also makes cold builds faster.

Let's use MySocials to showcase this. The Next.js 15 dev server took 35.6 seconds to initiate and run:

After upgrading the project to Next.js 16, the dev server launch time was cut down to 6 seconds:

A warm build was even quicker at 3.8 seconds:

We also found that compilation in development mode took Next.js 15.1 seconds to complete, while its v16 counterpart was done in 21 seconds. After editing the footer and reloading, v15 recompilation in Dev mode took 10.6 seconds, compared to 4.6 seconds in Next.js 16. In both instances, the changes were made available to the browser almost immediately thanks to HMR. Following additional rounds of testing and benchmarking, we found that a full Next.js 15 build took 251.67 seconds, whereas the v16 build took 36.25 seconds.

Here's a side-by-side breakdown:

Aspect	Next.js 15 (WebPack)	Next.js 16 (Turbopack)
Cold Startup Time	35.6s	6s (Nearly 6x faster)
Warm Startup Time	8.6s	3.8s (2.2x faster)
Dev Compilation Speed	121.7s	21.5s (5~x faster)
HMR / Fast Refresh Latency	10.6s	4.6s (2~x faster)
Full production build	251.67s	36.25s (7~x faster)

Why this matters

Next.js 16's new optimizations and features let you rapidly apply and test hot fixes. These are meaningful performance boosts that have short and long-term implications on the productivity of your team. Turbopack's incremental compilation is particularly favorable in monorepos and large apps with hundreds of packages. Next.js 16 only recompiles files that have new changes (along with their direct dependencies), saving you time and improving your project's ability to scale.

With that being said, it's important to note that Turbopack is still maturing, and several bugs have been reported and still persist. Contrastingly, Webpack is stable, reliable, and extremely well-supported with a thriving ecosystem of plugins and loaders. You could also always use Turbopack as an alternative bundler in Next.js 15.

However, Next.js 15 uses an alpha version of Turbopack. This means it's less stable and can only be run in dev mode. Features like Cache Components and React 19.2 support are also missing. Upgrading to Next.js 16 would allow you to take full advantage of Turbopack's capabilities. Although Turbopack is the default bundler, Next.js 16 still has full Webpack support. This means you can revert to it at any time after upgrading.

Cache components and use cache

v16 changes how caching is handled in Next.js. Where its predecessor used implicit caching as a default, Next.js 16 introduces a new explicit caching model.

The problem with implicit caching in Next.js 15

Next.js automatically decides what to cache and for how long, based on the APIs you use and where you use them. For example, data returned from fetch requests is uncached unless you explicitly opt in, but rendering work and certain data requests are cached per request lifecycle to improve performance.

Because earlier versions of Next.js leaned heavily on implicit caching, many developers assumed that repeated calls to the same endpoint would be cached automatically. However, if you didn't explicitly set options like force-cache or next:{ revalidate: 60 }, every request would hit the API fresh. This led to unexpected performance issues, especially when developers thought they were benefiting from caching but weren't.

Route segment caching was as confusing (if not more) because of how extensively caching behavior relied on the data-fetching API used in the segment. This meant that each route segment, whether a page, layout, or nested child, would be cached non-uniformly. For example, a segment using getStaticProps would be cached at build time, while one using getServerSideProps would fetch fresh data on every request. This implicit link between API choice and caching made it difficult to reason about how segments behaved without carefully tracking which API was in play.

It could also lead to accidental over-caching. If developers used getStaticProps without a revalidate interval, pages would remain cached indefinitely, even if the underlying data changed. This led to stale content being served to users until a new build was triggered.

How Next.js 16 improves caching

Next.js 16 makes caching explicit, granular, and predictable through Cache Components. This feature addresses the pitfalls of fetch caching by letting you wrap expensive components and functions in a cache boundary that you specify through the "use cache" directive. It essentially allows you to control how these elements should be cached and revalidated.

This goes for route segment caching, too. Cache Components provide each segment or component with its own cache boundary. Because caching is opt-in and configurable, the risk of over-caching reduces.

Code example: before vs. after

Here's an example showing implicit caching in v15:

// pages/products.js (Next.js 15)
export async function getStaticProps() {
  const res = await fetch("https://api.example.com/products");
  const products = await res.json();
  return {
    props: { products },
    revalidate: 60, // refresh every 60 seconds
  };
}

export default function ProductsPage({ products }) {
  return (
    <ul>
      {products.map(p => <li key={p.id}>{p.name}</li>)}
    </ul>
  );
}

The getStaticProps function automatically caches the page at build time as static HTML until the next build is initiated. You'll notice the inclusion of revalidate in the return. Without it, you risk accidental overcaching (stale data until a rebuild).

v16 uses explicit caching:

// app/products/page.js (Next.js 16)
export async function getProducts() {
  "use cache"; // Explicit directive: cache this function's result
  const res = await fetch("https://api.example.com/products");
  return res.json();
}

export default async function ProductsPage() {
  const products = await getProducts();
  "use cache"
  return (
    <ul>
      {products.map(p => <li key={p.id}>{p.name}</li>)}
    </ul>
  );
}

In this example, the "use cache" directive is called on both the function (getProducts) and the component level (<ul>). The getProducts function result is cached, while the rendered UI fragments are refreshed (revalidated) based on the default profile revalidation rules. You can also place the "use case" on the file-level (instead of on each function/component), essentially caching the entire page.

While the v16 example uses time-based intervals in its current form, you can explicitly set it to use tag-based invalidation or manual refresh. This lets you set clear revalidation rules, making updates predictable and easier to manage, instead of relying on implicit Incremental Static Regeneration (ISR) rules. By moving from implicit, API‑driven caching in v15 to explicit cache boundaries in v16, developers gain a simpler, more consistent mental model. You no longer have to guess how caching interacts with route segments or fetch calls; it's declared in code and easy to reason about.

Routing and edge changes

Next.js 16 replaces middleware.ts with proxy.ts. This change was mainly to clarify the layer's role. Many developers found the name misleading or confusing (and for good reason). It was never a catch-all "middleware" layer, but instead a proxy that intercepts and forwards requests at the network boundary.

The Problem with Next.js 15's middleware.ts

Before the change, many teams used the middleware (now proxy) layer for complex logic (authentication, database queries, heavy transformations), which was not its intended purpose. Developers would confuse it with Express.js middleware, which encouraged developers to treat it as a general logic layer rather than a lightweight routing tool.

Next.js 16's introduction of proxy.ts

With proxy.ts, routing rules are explicit and separated from caching. Proxy runs at the edge by default, which aligns with Vercel's push toward edge‑first architecture for Next.js 16 and future iterations of the framework. This ensures rewrites and redirects happen close to the user (edge side), improving latency.

Developers should think of the proxy as a network gatekeeper, not a hidden logic layer. This reduces confusion around where to put caching, revalidation, or authentication logic.

Migration considerations

When migrating from middleware.ts/middleware.js in Next.js 15 to proxy.ts/proxy.js in Next.js 16, you need to consider how your existing middleware logic maps to proxy rules. Simple routing logic from middleware maps cleanly to proxy rules, but heavier business logic should be moved into route handlers or server actions. In practice, if your middleware only rewrote /old-route to /new-route or redirected unauthenticated users to /login, those rules migrate directly into proxy.ts without much change.

The second consideration is identifying what breaks and what doesn't. What breaks are cases where the original middleware layer was overloaded with responsibilities it wasn't designed for, like database queries, complex authentication flows, or caching logic. You'll need to refactor those into server components, API routes, or dedicated backend services. The core routing behaviors, like rewrites, redirects, and header manipulation, are safe.

Let's say your middleware.js file looks like this:

// middleware.js (Next.js 15)
import { NextResponse } from "next/server";

export function middleware(req) {
  const url = req.nextUrl;

  // Redirect unauthenticated users
  if (!req.cookies.get("auth")) {
    return NextResponse.redirect(new URL("/login", req.url));
  }

  // Rewrite /old-route to /new-route
  if (url.pathname === "/old-route") {
    return NextResponse.rewrite(new URL("/new-route", req.url));
  }

  return NextResponse.next();
}

Your migrated proxy.js will look like this:

// proxy.js (Next.js 16)
import { proxy } from "next/server";

export default proxy((req) => {
  const url = req.nextUrl;

  // Redirect unauthenticated users
  if (!req.cookies.get("auth")) {
    return Response.redirect(new URL("/login", req.url));
  }

  // Rewrite /old-route to /new-route
  if (url.pathname === "/old-route") {
    return Response.rewrite(new URL("/new-route", req.url));
  }

  // Forward all other requests
  return Response.next();
});

You'll notice that redirects and rewrites migrate directly. The logic is almost identical. Any mention of "middleware" is replaced with "proxy".

React 19.2 integration

Next.js 16 integrates React 19.2 (where Next.js 15 was built on React 18) as its default React runtime, bringing stable support for Server Components, Actions, and the React Compiler. This tight integration makes caching, async server APIs, and edge execution more predictable and efficient.

React 19.2 View Transitions

View Transitions uses the browser's native View Transitions API to create smooth, animated changes between pages or UI states. It eliminates the need for complex animation libraries as the browser handles transitions. View Transitions also allows for seamless page‑to‑page animations, reducing the "hard cut" feel of traditional navigation.

useEffectEvent

Another notable feature introduced in React 19.2 is useEffectEvent. It lets you extract non‑reactive logic from your effects into a reusable function called an Effect Event, ultimately solving the stale closure problem. useEffectEvent ensures your effects always have access to the latest props and state without unnecessary re‑renders.

Imagine you're building a chat app. When a user connects to a chat room, you want to show a notification styled with the current theme (light or dark). Your code in Next.js 15 (without useEffectEvent) would look like this:

import { useEffect } from "react";

function ChatRoom({ roomId, theme }) {
  useEffect(() => {
    const connection = createConnection("https://example.com", roomId);
    connection.on("connected", () => {
      showNotification("Connected!", theme); // captures theme
    });
    connection.connect();
    return () => connection.disconnect();
  }, [roomId, theme]); // re-runs whenever theme changes
}

The notification logic is placed directly inside useEffect. If the theme changes, the effect re‑runs unnecessarily, tearing down and reconnecting the chat. The Next.js 16 rewrite would look something like this:

import { useEffect, useEffectEvent } from "react";

function ChatRoom({ roomId, theme }) {
  const onConnected = useEffectEvent(() => {
    showNotification("Connected!", theme); // always uses latest theme
  });

  useEffect(() => {
    const connection = createConnection("https://example.com", roomId);
    connection.on("connected", () => {
      onConnected(); // stable, no stale closure
    });
    connection.connect();
    return () => connection.disconnect();
  }, [roomId]); // only re-runs when roomId changes
}

The use of useEffectEvent keeps the connection stable while still using the latest theme for notifications. Dependencies are simpler, the chat connection isn't torn down unnecessarily, and notifications reflect the current theme.

The implications for Next.js apps

View Transitions and useEffectEvent both reduce the reliance on custom. In React 18 and earlier, developers often wrote hooks to manage stale closures in effects or to synchronize state with subscriptions. useEffectEvent provides a stable callback that always sees the latest props and state. Similarly, View Transitions removes the need for custom hooks or context providers to manage navigation animations. Together, these features cut down on boilerplate and make Next.js apps leaner and easier to maintain.

These features also contribute to more predictable rendering behavior. useEffectEvent ensures effects don't re‑run unnecessarily, keeping connections or listeners stable while still reflecting fresh state. View Transitions integrates directly with the App Router, so transitions happen consistently across route changes without unexpected flickers or mismatched states. For developers, this means fewer surprises in how React and Next.js handle updates, and for users, it means smoother, more reliable interactions.

Stable support for the React Compiler

Next.js 16 ships with React 19.2, and that includes the React Compiler as a first‑class integration. In practice, this means Next.js developers no longer need to scatter useMemo, useCallback, or React.memo throughout their codebase to prevent unnecessary re‑renders.

The compiler analyzes your components at build time and automatically applies memoization optimizations. For Next.js apps, this is especially impactful because of the App Router and Server Components model. Server Components already reduce client‑side JavaScript, and the compiler ensures that the remaining client components render efficiently without developer micromanagement. Combined with Next.js 16's explicit caching, you get predictable performance both on the server and client.

Developers can now write straightforward React code in Next.js without wrapping everything in memoization hooks. The compiler handles performance tuning automatically, so users experience smoother interactions.

Breaking changes and deprecations

The move from middleware to proxy wasn't the only potential project-breaking change that was introduced with Next.js 16. The next/image component shifted toward native browser features and simpler defaults.

Lazy‑loading is now applied automatically, responsive sizing no longer requires the layout prop, and styling props like objectFit and objectPosition have been deprecated in favor of plain CSS. These changes reduce abstractions but require migration if you relied on older defaults.

Audit and migration considerations

You'll need to remove deprecated props like layout, objectFit, and objectPosition, then add loading=eager or priority to prevent lazy-loading delays. Use fill for full‑width images or explicit dimensions for fixed sizing. This provides more responsive control.

For styling, move image fit/position logic into CSS classes for consistency. This helps manage the Cumulative Layout Shift (CLS). Tools like Lighthouse or WebPageTest can help you verify if images are causing layout shifts. To optimize the delivery of your images, use modern formats like WebP and AVIF. Next.js 16 automatically serves optimized versions, but it's always a good idea to confirm that your source assets are high-quality.

Remember to check file sizes. Large hero images should be compressed without visible quality loss. In addition to this, ensure images are cached at the edge for fast delivery.

AMP support Is deprecated

In Next.js 16, AMP support is fully deprecated and removed. You can no longer configure pages with amp: true or amp: 'hybrid', and the AMP optimizer is gone. Teams and organizations that had invested in building AMP‑specific pages for mobile performance or SEO will be the most impacted by this change.

AMP support deprecation also affects developers who built workflows around AMP's restrictions, such as limiting JavaScript usage, relying on AMP‑specific components, or configuring hybrid AMP pages. Those patterns are no longer supported, so developers need to migrate to Next.js's unified rendering model.

Instead of AMP's strict markup, they'll lean on Server Components, Actions, Turbopack, and explicit caching to achieve performance goals. This requires some refactoring, but ultimately simplifies codebases by removing the need for parallel AMP templates.

Migrating from AMP

SEO has shifted over the last few years. Google no longer gives AMP pages preferential treatment. Instead, Core Web Vitals (CLS, LCP, INP) are the ranking signals. A well‑optimized Next.js page can perform just as well as AMP. AMP required separate templates and restrictions. Next.js 16 lets you build a single React app with consistent tooling, reducing complexity.

When migrating from AMP, you first need to audit your project's AMP pages. This means identifying any pages using amp: true or amp: 'hybrid'. Next, remove all AMP configs and consolidate into standard Next.js routes.

Implement Server Component to minimize client JS, then move styling into CSS instead of AMP-specific markup. Replace AMP-restricted forms with Actions for mutations.

Migration strategy: how to upgrade safely

First, consider whether you should upgrade. For greenfield projects, upgrading to Next.js 16 makes sense. Starting fresh means you can adopt the new primitives we've discussed without worrying about legacy code. You'll be building on the latest architecture from day one, which reduces technical debt and ensures your app is aligned with the direction Next.js is heading.

For mature production apps, the decision requires more caution. Migrating from Next.js 15 involves rethinking middleware, auditing caching behavior, and replacing unstable APIs with their stable equivalents. If your app is business‑critical, you'll want to plan a phased migration, starting with staging environments and regression testing before rolling out to production. The payoff is significant. You'll get better performance and more predictable caching. However, the risk of breaking existing flows means you should approach the upgrade deliberately rather than rushing.

Team size and risk tolerance also play a big role. Smaller teams with limited resources may prefer to wait until the ecosystem stabilizes further, since they may not have the bandwidth to troubleshoot regressions. Larger teams, or those with higher risk tolerance, can benefit from adopting Next.js 16 earlier, especially if they have the capacity to run performance regression tests, audit caching, and adjust CI/CD pipelines.

The right timing depends on your context, but once you've weighed those factors, the next step is to define a clear upgrade path.

Recommended upgrade path

The quickest way to upgrade your Next.js project from version 15 to 16 is by using the upgrade codemod. Open a terminal, navigate to your project's root folder, and run the following command:

npx @next/codemod@canary upgrade latest

Note: Ensure that Node.js is installed before running the above command.

The upgrade codemod is interactive. So once it's done downloading the necessary packages, it will present you with a set of upgrade options that are relevant to your project. These include:

Adding the new Turbopack configuration to your next config file.
Migrating from next lint to the ESLint CLI.
Switching over to proxy from the middleware convention.
Remove experimental_ppr Route Segment config from App Router pages and layouts.
Drop all unstable_ prefixes from stabilized APIs.

You may not see some of these options if they're already up-to-date in your project. For instance, if your project is already using the latest ESLint CLI, it won't appear in the list:

By default, all update options are toggled on. Once you're ready, you can hit the Enter key to perform the updates.

Alternatively, you can upgrade your project manually, especially if the upgrade codemod fails.

Manually upgrading Next.js 15 to 16

Run the following command to upgrade Next.js to the latest version:

npm install next@latest

You can then upgrade React using the following command:

npm install react@latest react-dom@latest

Note: If you're using TypeScript, you'll need to update @types/react and @types/react-dom.

Some libraries may not yet support React 19. Fortunately, Next.js 16 supports React 18.2.0+. That means, if you find version mismatches or peer dependency conflicts, the best way to get around this is by upgrading or downgrading to React 18 (which Next.js 16 still supports), like this:

npm install react@18 react-dom@18

Next, you'll need to migrate from the middleware to proxy. First, find the middleware file in your root folder (middleware.js or middleware.ts) and rename it to proxy (proxy.js if you're using JavaScript, or proxy.ts if you're using TypeScript).

Next, open your freshly renamed proxy file and replace the middleware export function to proxy (if available):

export function proxy(request: Request) {}

You'll also need to replace any configuration flags that contain middleware as part of their name. For example, you'll need to change skipMiddlewareUrlNormalize to skipProxyUrlNormalize.

Alternatively, you can run the migration codemod from your terminal, which will perform all the migration steps for you:

npx @next/codemod@canary middleware-to-proxy .

If your Next.js 15 project uses experimental Partial Pre-Rendering (PPR), you'll need to remove every instance of it (flags, configuration options, and route-level segments). Vercel provides another helpful codemod to perform this action. Run the following command from your terminal:

npx @next/codemod@latest remove-experimental-ppr .

You can then opt into PPR by adding the cacheComponents option to your next.config.js file:

/** @type {import('next').NextConfig} */
const nextConfig = {
  cacheComponents: true,
}
module.exports = nextConfig

Next.js 16 stabilized a large number of plugins that were marked unstable in version 15. To ensure that your Next.js 16 project isn't calling deprecated APIs, you'll need to remove every mention of the unstable_ prefix from all stabilized APIs. You can do this manually or use the codemod:

npx @next/codemod@latest remove-unstable-prefix .

Enabling Webpack as a fallback

If your project relies on WebPack loaders, plugins, or has a custom configuration, you can opt out of Turbopack. You can run Dev with the Webpack flag:

npx next dev --webpack

Alternatively, you can edit the script section of your package:

"scripts": {
  "dev": "next dev --webpack",
  "build": "next build --webpack",
  "start": "next start",
  "lint": "next lint"
},

This will force your project to use WebPack in both the production and development builds. If you need to use Turbopack for one of these builds (for instance, dev), you can simply remove the --webpack flag.

Post-upgrade tooling and testing tips

Developers looking for the latest bug fixes and feature updates may be tempted to opt into canary releases. Canary releases aren't guaranteed to be stable, as they may contain unfinished APIs, regressions, or performance issues.

How to approach canary releases

For most teams, the safer approach is to test canary builds in local development or staging environments, where you can evaluate new features without exposing end users to potential instability. You can run the following command to pin your project to the latest Next.js canary build:

npm install next@canary

Opting into canary releases is most beneficial for developers who maintain libraries, frameworks, or large applications that need to anticipate changes. Canary builds are best for local development, staging, or feature branches. Avoid deploying them to production unless you're comfortable with instability.

Whether you're running the Canary or official stable release, you'll want to combine Next.js 16's tooling upgrades with a set of targeted testing practices. The first tool you should acquaint yourself with is the Next.js DevTools MCP Server.

Using the Next.js DevTools MCP server

The Next.js DevTools MCP Server is designed to give developers deep visibility into how their application is behaving at runtime, especially around caching and rendering. Prior to its introduction, developers often had to rely on logs, headers, or trial‑and‑error to understand what was cached, when it would revalidate, and why certain components were re‑rendering.

Use it to inspect cache boundaries, to see exactly where cache() is being applied to your code. This is crucial because caching in Next.js 16 is explicit.

For revalidation timings, DevTools provide a clear view of how long cached data is valid and when it will be refreshed. Instead of guessing whether a component will revalidate after 30 seconds or only on demand, you can see the exact timing in the DevTools panel. This helps you audit your ISR or Cache Component settings and ensures that your content stays fresh without overloading your backend.

DevTools can also show you whether a component was served from cache, revalidated, or freshly rendered. This is especially important in Next.js 16 because PPR means parts of a page may be cached while others are dynamic.

In addition to the above, you'll also need to audit the Turbopack's cache behavior.

Auditing Turbopack's cache behavior

Turbopack now writes build artifacts into a persistent cache directory .next/cache. It's important to inspect the size and contents of this folder from time-to-time, especially if you're experiencing performance dips or build issues. Delete the contents of this folder to force Turbopack to rebuild everything from scratch. You can then measure how fast your rebuilds are against previous builds.

To measure how long builds take on Linux/macOS machines, you can use:

time npm run build

Or the following for Windows machines:

Measure-Command { npm run build }

Conclusion

Next.js 16 introduces proxy.js, Cache Components, and Turbopack's file cache to give developers clearer boundaries and faster builds.

Migrating from 15 to 16 requires teams to adapt to a new philosophy. Routing logic is now separated cleanly from authentication, caching is transparent and auditable through DevTools MCP, and build performance benefits from persistent caching. These changes reduce guesswork, improve scalability, and align Next.js more closely with modern React practices.

Ultimately, Next.js 16 is less of an incremental update and more of a re‑architecture. It challenges developers to rethink how they structure applications, but rewards that effort with faster builds, clearer caching strategies, and a more stable foundation for future growth.

Authentication, access control, and user management are critical components of any Next.js app. Use Descope's no / low code workflows to easily add natively embedded auth to your Next.js app without worrying about custom code or keeping up with breaking changes. You can also use Descope integrations on the Vercel Marketplace to add auth for your users and MCP servers in a few clicks. Sign up for a free Descope account to get started.

OAuth vs. API Keys for Agentic AI

Mrunank Pawar — Fri, 17 Apr 2026 15:00:00 +0000

This blog was originally published on Descope.

If you're a senior developer or architect, you've likely weighed the OAuth vs. API keys tradeoff many times to balance simplicity against security and convenience against control. But those API security concerns always assumed traditional API clients: web apps, mobile apps, and predictable server-to-server integrations. Agentic AI systems challenge those assumptions.

Unlike traditional API clients, agentic AI systems are autonomous, tool-using, and inherently non-deterministic. They make real-time decisions, chain multiple API calls together, and sometimes take actions their creators never explicitly programmed. When an AI agent can decide to delete your production database or book a flight on your behalf, the stakes of API authentication are high, and accidents happen. In this article, you'll reexamine the outstanding debate between OAuth and API keys through the lens of agentic AI.

What are API keys?

If you've used paid APIs from services like Claude, OpenAI, or Mailgun, you've already used API keys. API keys are simple, static credentials; typically long alphanumeric strings that act as both identifier and password rolled into one. They're given by API providers and included in requests, usually as a header or query parameter, to authenticate the caller.

How API keys work

The workflow is straightforward. A developer generates an API key from a provider's dashboard, embeds it in their application, and sends it with every API request:

GET /data HTTP/1.1
Host: api.example.com
Authorization: Bearer sk_live_a8f3j29dk3j2d9fj2k3d
Accept: application/json

The server validates the key against its database and either grants or denies access. It doesn't involve any redirects, token exchanges, or complexity.

Traditional use cases

API keys have been used in machine-to-machine (M2M) authentication for years, in controlled environments such as internal microservices, CI/CD pipelines, monitoring tools, etc.

Strengths / benefits of API keys

There's a reason API keys remain popular:

Simple to implement and deploy: No complicated flows, no authorization servers, no token management infrastructure.
Minimal overhead: No redirects, no token juggling, no refresh logic.
Useful for low-risk, tightly controlled systems: Where you trust the environment and the code using the key.

For instance, if a script syncs data between two internal databases at 3 a.m., using API keys is perfectly fine.

Limitations of API keys

The following are some shortcomings of API keys:

Long-lived and static by default: API keys have no built-in expiration mechanism. Once issued, a key remains valid until explicitly revoked. How and when it's revoked depends on provider tooling and team discipline.
No scopes: API keys have no standardized concept of permissions. When it does exist, access control is defined ad hoc, per provider. The result is inconsistent granularity across services and a lack of interoperability.
Hard to rotate at scale: Rotating keys across dozens of services means coordinating deployments and risking downtime.
No built-in user delegation: API keys represent the application, not a specific user. There's no way to say "this action was taken by Alice".
Limited auditability and traceability: Log entries show the API key was used, but not by whom, why, or in what context.

It's worth noting that individual providers have closed some of these gaps independently. For example: GitHub supports fine-grained personal access tokens (PATs) with repository-level scoping and expiration. AWS allows per-key policy for its Key Management Service (KMS). Anthropic and OpenAI both offer workspace-scoped keys with configurable permissions. But each of these is a proprietary implementation: different APIs, different defaults, different enforcement. An agentic system that calls tools across five providers encounters five separate permission models with no single standard determining how keys are issued, scoped, rotated, or revoked. OAuth's value in this context isn't that it can do things API keys theoretically can't, but that it does them consistently, interoperably, and by a shared specification.

What OAuth provides over API keys

If you've ever clicked "Login with Google" or "Login with LinkedIn" on a website, you've seen OAuth 2.0 in action.

OAuth 2.0 fundamentally rethinks API authentication by separating two concerns that API keys conflate: who you are (authentication) and what you can do (authorization).

Instead of a single static credential, OAuth uses short-lived access tokens granted through explicit authorization flows. These tokens carry specific permissions (called scopes) that define exactly what actions the bearer can perform.

Here are the key ideas of OAuth that make it more secure inherently:

Separation between authentication and authorization: With API keys, proving your identity and getting permissions are the same thing. OAuth splits these apart. An identity provider verifies who you are, an authorization server decides what you can access, and a resource server validates your token. Each component has a single, well-defined job.

Fine-grained scopes defining permissions: Instead of all-or-nothing access, you request specific scopes like read:calendar or write:events. The authorization server issues a token that carries only those permissions. The API server enforces these boundaries automatically.

A simplified OAuth request looks like this:

GET /oauth/authorize?
  response_type=code
  &client_id=cal_agent_a8f3j29dk3
  &redirect_uri=https://myagent.com/callback
  &scope=read:calendar+write:events
  &state=x8f2k9d3j2a
  &code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM
  &code_challenge_method=S256 HTTP/1.1
Host: auth.calendar.com

Token-based, short-lived, revocable access: Access tokens typically expire within an hour. When they do, the client uses a refresh token to get a new one without user intervention. But here's the key advantage: you can revoke a refresh token instantly, cutting off access without changing client credentials or redeploying code. The blast radius (extent of damage or impact in case of a leak) of a compromised token is limited to minutes, not months.

Standardized token exchange and per-action downscoping: OAuth defines a standardized mechanism for exchanging one token for another with different scopes, audiences, and lifetimes through OAuth Token Exchange (RFC 8693).

This enables a critical pattern for agentic AI systems: an agent can hold a base delegated token, then exchange it at runtime for narrowly scoped, ephemeral tokens tailored to each specific action or tool invocation.

For example:

An agent exchanges its base token for a calendar:read token when analyzing schedules
It exchanges again for a refund:create token scoped to a specific transaction
Each exchanged token is audience-restricted to the exact API being called and expires within minutes

This ensures agents always operate with the minimum permissions required at the moment of action, dramatically reducing blast radius and preventing privilege accumulation over time.

API keys lack any standardized, interoperable mechanism for token exchange or dynamic downscoping. Any similar behavior must be custom-built, inconsistent, and difficult to audit.

Ability to represent human intent through consent flows: Before any client gets access, the user sees a consent screen listing exactly what permissions are being requested. They click "Allow" or "Deny". This explicit grant means the client (say: an agent) operates with delegated authority, not stolen credentials. Since the user gives permission, it gets recorded.

The diagram below shows how authentication, scopes, consent, and token lifecycle work together in the OAuth flow:

OAuth benefits for modern architectures

The capabilities of OAuth translate into concrete architectural advantages, especially as systems become more distributed and autonomous.

Delegation model aligns with trust boundaries: OAuth is designed for third-party access. An AI agent accessing your Google Calendar is fundamentally a third party, even if you built it yourself. OAuth's delegation model reflects this reality. The agent doesn't hold your password. It holds a limited access that you approved.

Granular access provides least privilege by default: Scopes enforce the principle of least privilege automatically. An agent building calendar summaries gets read:calendar only. An agent scheduling meetings gets read:calendar and write:events. An agent never gets delete:account unless you explicitly grant it.

Revocation and observability of token usage: Every access token is traceable to a specific authorization grant, user, scope set, and timestamp. Your authorization server logs show exactly which agent did what, when, and under whose authority. If an agent misbehaves, you can revoke its token without affecting other systems or users.

Better fit for ecosystems with distributed autonomy and risk: When multiple agents operate semi-independently, each with different trust levels and capabilities, OAuth provides the identity and permission infrastructure to manage that complexity safely. You're not sharing one master key across a dozen autonomous systems. You're issuing narrowly scoped, individually revocable tokens.

Agentic AI: a new category of API client

Traditional API clients follow a script. A cron job runs at midnight, calls API endpoints sequentially, processes the data, and exits. A mobile app waits for user taps, makes predictable API calls, and displays results. The behavior is deterministic. Agentic AI systems are largely autonomous, operating on goals rather than hardcoded instructions. They learn from context, adapt to situations, and generate action sequences you never explicitly programmed.

Consider a customer support agent built with an LLM. A user asks, "Why was I charged twice last month?" The agent doesn't follow a fixed script. Instead, it:

Reasons that it needs to check billing history.
Calls your payments API to retrieve customer transactions.
Analyzes the results and notices a duplicate charge.
Decides to check your refunds API to see if it was already addressed.
Determines it wasn't refunded.
Calls your refunds API to initiate a refund.
Responds to the user with confirmation.

As a developer, you don't program steps 1 through 7 explicitly. Instead, you give the agent access to tools (the APIs), describe what each tool does, and let it figure out the sequence. The agent chains multiple API calls, makes contextual decisions, and takes financial action autonomously.

This is fundamentally different from a webhook that processes a payment and triggers a predefined workflow. The agent's behavior emerges from its training and the situation at hand. It operates beyond simple scripts or predictable machine-to-machine workflows.

Why these characteristics matter for auth

This autonomy creates new security requirements that API keys were never designed to handle:

Need for granular, action-bound permissions: When an AI agent can dynamically choose which APIs to call, you cannot give it blanket access to everything. You need to constrain it to specific actions: read billing data, yes; initiate refunds up to $100 USD, maybe; delete customer accounts, absolutely not.
Need to audit and trace agent actions at fine resolution: When something goes wrong, you need logs that show exactly what the agent did, why, and under whose authority. "API key used at 3:47 PM" is not enough. You need "Agent-CustomerSupport-v2 initiated $47 USD refund for user Alice under scope refunds:create:limited at 3:47 PM."
Need for safe delegation of user authority without exposing secrets: The agent acts on behalf of users, but it should never hold their passwords or master credentials. It needs delegated, scoped authority that represents user intent.
Need for revocable, time-bounded permissions to reduce blast radius: If an agent starts misbehaving for any reason, you should be able to cut off its access immediately with instant revocation.

API keys can't deliver this level of control. You need OAuth for its granular scope enforcement and built-in token revocation.

Comparing API keys vs. OAuth in agentic AI scenarios

Let's look at how a few real-life scenarios could use API Keys vs. OAuth.

Scenario 1: an agent managing a user's calendar

Consider an AI assistant that helps users manage their work calendar by reading events, finding conflicts, and suggesting optimal meeting times.

With API keys

The agent uses a static key with full calendar access:

import requests

API_KEY = "sk_live_calendar_full_access_key"
headers = {"Authorization": f"Bearer {API_KEY}"}

# Agent can read, write, delete anything
events = requests.get("https://api.calendar.com/events", headers=headers)
requests.delete("https://api.calendar.com/events/important-meeting", headers=headers)

The problems are serious. The API key grants complete access to all calendar operations. The agent can delete events, modify attendees, or clear entire calendars, even though it only needs to read events. If the key leaks through logs, prompt injection, or model output, attackers gain full calendar control. There's no user consent, no audit trail showing which specific agent performed which action, and no way to distinguish agent requests from legitimate server operations in logs.

With OAuth

The user explicitly grants limited access through a consent flow:

from requests_oauthlib import OAuth2Session

# Agent requests only read access
oauth = OAuth2Session(
    client_id='calendar_agent_client',
    scope=['read:calendar']
)

# User sees: "Calendar Agent wants to: Read your calendar events"
# User clicks "Allow"
# Agent receives a token limited to reading
token = oauth.fetch_token(
    'https://auth.calendar.com/token',
    authorization_response=callback_url
)

# This works
events = oauth.get('https://api.calendar.com/events')

# This fails - token doesn't have write:calendar scope
oauth.post('https://api.calendar.com/events', json={...})  # 403 Forbidden

The token expires after an hour. If the agent misbehaves, the user revokes access instantly from their security settings. Audit logs clearly show: "calendar_agent_client accessed user Alice's calendar with scope read:calendar at 2:34 PM". The blast radius is contained.

Scenario 2: an agent automating developer tooling

Now let's consider an AI agent that helps developers by automatically creating GitHub issues from Slack conversations, assigning them to the right team members, and updating project boards.

With API keys

A GitHub personal access token with full repo access sits in the agent's configuration:

GITHUB_TOKEN = "ghp_full_repo_access_token"
headers = {"Authorization": f"token {GITHUB_TOKEN}"}

# Agent can do anything
requests.post("https://api.github.com/repos/company/prod/issues",
    headers=headers,
    json={"title": "Bug found"})

# Including destructive operations it shouldn't
requests.delete("https://api.github.com/repos/company/prod",
    headers=headers)

The static token allows the agent to delete repositories, modify branch protection rules, or leak source code. There's no time limit, no scope restriction, and no clear audit trail linking actions back to the specific agent instance.

With OAuth

The agent requests narrowly scoped access:

# Agent requests specific permissions
oauth = OAuth2Session(
    client_id='dev_agent_client',
    scope=['repo:issues:write', 'project:read']
)

# Token is bound to specific repos and actions
token = oauth.fetch_token(...)

# Agent can create issues
oauth.post('https://api.github.com/repos/company/prod/issues',
    json={"title": "Bug found"})

# But cannot delete repos or access code
oauth.delete('https://api.github.com/repos/company/prod')  # 403 Forbidden

OAuth scopes restrict the agent to creating issues and reading project boards. The token expires after an hour and can be revoked if the agent starts creating spam issues. GitHub's audit log shows exactly which agent, acting under whose authority, performed each action.

Scenario 3: multi-agent workflows

Now consider an agentic system where multiple specialized agents collaborate: one agent researches competitors, another drafts marketing copy, and a third publishes content to your CMS.

With API keys

All agents share the same CMS API key:

SHARED_CMS_KEY = "cms_full_access_key"

# Research agent (should only read)
research_agent.set_credentials(SHARED_CMS_KEY)

# Writing agent (should read and draft)
writing_agent.set_credentials(SHARED_CMS_KEY)

# Publishing agent (should publish drafts)
publishing_agent.set_credentials(SHARED_CMS_KEY)

# All have identical, full access

This creates multiple problems. The research agent can accidentally publish content. The writing agent can delete published articles. If any agent is compromised, all three are compromised because they share credentials. Server logs show "CMS key used" but not which agent or why. There's no way to represent each agent's actual role and permissions.

With OAuth

Each agent gets its own identity and scoped token:

# Research agent - read-only access
research_oauth = OAuth2Session(
    client_id='research_agent',
    scope=['content:read']
)

# Writing agent - read and draft
writing_oauth = OAuth2Session(
    client_id='writing_agent',
    scope=['content:read', 'content:draft']
)

# Publishing agent - publish only
publishing_oauth = OAuth2Session(
    client_id='publishing_agent',
    scope=['content:publish']
)

Each agent operates with least privilege. The research agent cannot modify content. The writing agent cannot publish. The publishing agent cannot delete. If the writing agent is compromised through prompt injection, the attacker gains only drafting capabilities, not publishing or deletion. Audit logs clearly attribute each action to a specific agent identity with specific permissions.

Why the Model Context Protocol mandates OAuth

The Model Context Protocol (MCP) is an open standard defining how AI systems should securely interact with external tools and data sources. MCP provides a structured way for agents to discover available tools, understand their capabilities, and invoke them safely.

While MCP makes authorization optional for low-risk scenarios, it mandates OAuth 2.1 when agents access user data or act on behalf of users, precisely the scenarios where autonomous agents make real-time decisions about tools and actions.

MCP encourages OAuth 2.1 for the ability for every tool to explicitly define its required access scopes. When an agent wants to use a tool, it must authenticate using OAuth flows designed for agents running on servers without a traditional user interface (i.e., headless). This typically means device flow (where users authorize on a separate device by entering a code) or authorization flows with Proof Key for Code Exchange (PKCE): a security extension that prevents authorization code theft by requiring a secret only the legitimate client knows. These flows ensure users grant explicit consent for the specific permissions each tool needs.

MCP requires auditable, revocable, and safe delegation of authority. Each tool invocation is traceable to a specific token, scope set, and user consent. When an agent misbehaves or a tool becomes compromised, admins can revoke access immediately without affecting other tools or redeploying code.

API keys lack the granularity, traceability, and revocation mechanisms MCP's security model requires. By mandating OAuth, MCP ensures agentic systems operate within clearly defined, user-controlled permission boundaries.

When API keys still make sense

OAuth isn't always the perfect choice. There are legitimate scenarios where API keys remain a more practical choice.

Non-agentic M2M automation: Internal microservice calls on private networks don't need OAuth's complexity. When Service A calls Service B within your infrastructure, both under your complete control, a rotated API key works fine. The same applies to simple backend processes with predictable behavior (i.e., nightly ETL jobs, monitoring scripts, deployment pipelines). These systems follow deterministic logic with no autonomous decision-making.

Low-risk or high-control environments: Internal admin tools accessible only from corporate networks, behind VPNs, with IP restrictions and vault-managed secrets, can safely use API keys. The infrastructure itself enforces security boundaries.

Startups or prototypes: Early-stage products validating product-market fit can use API keys to move fast. However, OAuth migration might be required for scaling.

Did you know? Major AI providers like OpenAI and Anthropic still use API keys for millions of users because they're authenticating developer applications, not autonomous agents acting on behalf of end users. When those applications need to perform user-specific actions with granular permissions, OAuth becomes necessary at that layer.

Quick implementation guidance and best practices

Use this decision tree to choose authentication based on your requirements:

For OAuth in agentic AI systems

Implement narrow scopes: Avoid wildcard permissions like admin:* or full_access. Define granular scopes that match actual operations: calendar:read, issues:create, content:draft.
Prefer short-lived access tokens with automatic refresh: Set access token expiration to one hour or less. Use refresh tokens to obtain new access tokens without user intervention.
Require explicit user consent flows: Users must see and approve exactly what permissions they're granting.
Bind agent identity to token issuance: Each agent instance should have its own client ID. This allows per-agent revocation and helpful audit trails.
Enable complete audit logging: Log every token issuance, refresh, and API call with agent identity, scope, timestamp, and user context.
Use Authorization Code Flow with PKCE and Device Code Flow: For agents running on servers or in automated environments, these flows provide secure authentication without traditional browser redirects.

For API keys

Rotate regularly and automatically: Implement 90-day rotation schedules with zero-downtime deployment strategies.
Store keys in secure vaults: Use dedicated secret management systems like Google Secrets Manager or similar.
Apply API rate limits and behavioral analytics: Monitor for unusual patterns that might indicate compromise.
Restrict IP addresses or environments: Limit key usage to known networks or infrastructure.
Transition to OAuth once agents enter the ecosystem: Plan this migration before adding autonomous capabilities.

Conclusion

Agentic AI is transforming API authentication requirements. The simplicity of API keys comes at a cost: no granular permissions, no revocation, and limited auditability. OAuth provides the delegation model, scoped access, and security controls that autonomous systems demand. With protocols like MCP mandating OAuth for tool access, the industry is converging on a clear standard for intelligent, autonomous systems.

OAuth implementation is becoming necessary for AI agents. Descope provides purpose-built authentication for agentic AI systems, with pre-configured OAuth flows, granular scope management, and agent identity infrastructure that scales from prototype to production.

Add Authentication and RBAC to a Webflow App

Mrunank Pawar — Wed, 15 Apr 2026 15:00:00 +0000

This blog was originally published on Descope.

Authentication and authorization are essential for controlling user access and actions within applications, ensuring the right people can do the right things. However, implementing these features can be complex and error-prone, especially in Webflow, where server-side logic isn't easily accessible. Ineffective management of sessions and user roles can expose your application to security vulnerabilities.

Consider a typical Webflow content management system (CMS) where team members collaborate on content but their access must vary based on their roles. Writers should manage only their own articles, while editors require full control to publish, delete, or oversee other authors' work. Role-based access control (RBAC) simplifies this by assigning roles—such as Writer or Editor—to users and granting permissions accordingly.

Traditionally, implementing authentication and RBAC required significant backend development and ongoing maintenance. With Descope, you can add these features to your Webflow app without writing complex backend code. Descope provides a visual workflow editor, Descope Flows, for authentication and integrated RBAC functionality, enabling you to add these features to your Webflow app without backend complexity. This tutorial will guide you through securing your Webflow CMS with Descope social login, email verification, and role-based permissions.

Setting up your Descope project and configuring an authentication flow

Before implementing authentication and RBAC in your application, let's set up the development environment and configure Descope to meet your needs.

Head over to the Descope website and create your free account. Once you've successfully created an account, you'll be guided through creating an authentication flow that matches your application's needs:

For a CMS application, you want to offer both email-based and social authentication to give users some flexibility in their preferred sign-in method.

Navigate to the Flows section in the Descope Console and click Start from scratch:

Since this flow handles both new user registration and existing user authentication for the CMS, you can name it "publishpro auth flow". The flow editor presents a visual canvas where you design the authentication experience:

Creating and adding elements to the authentication interface

You can now build the authentication interface by creating a Sign Up or Sign In screen. Click the + button to drag and drop a new screen. Inside the screen, click the screen body text element. On the right panel of the editor, go to the Content section and update the text to "Welcome to PublishPro". Then, scroll down to the Style section and set the style to the H2 element, as shown here:

Drag and drop a Container element from the list of elements in the left panel of the screen. Then drag and drop an Email input element and a Button element inside this container. Select the Button and rename its Text value to "Submit" on the right panel. Then adjust its width to fit that of the container by toggling the Fill container button. Here's what it should look like:

Adding social login

This setup handles email OTP authentication, providing a passwordless option for users. Next, you'll add social login as an alternative authentication method.

To clearly distinguish between the two authentication methods, add a divider element between the methods. On the left panel, scroll down to the TEXT section and drag and drop a Divider element below the Button element:

While still on the left panel, scroll to the BUTTONS section and add a Google button from the list of OAuth providers right under the divider. You can choose other OAuth providers from the existing list, but this example uses only Google:

With that in place, you can click the Done button to return to the canvas. Here, you see the newly created screen, so connect it to the START of the flow, as follows:

Linking the submit and socials buttons

The next step is to link the Submit and Socials buttons on the newly created Sign Up or Sign In screen to their respective actions, ensuring they trigger the intended functionality when clicked. Click the + button and select Action. Then, search for and add both Sign Up or In / OTP / Email and Sign Up or In / OAuth actions to the canvas. Connect the Submit button to the Sign Up or In / OTP / Email action to handle email authentication and connect the Socials button to the Sign Up or In / OAuth action to handle social login:

These custom actions contain both actions and screens that handle the common flows inherent in OTP and OAuth authentication methods.

Handling new and existing users

You also need to differentiate between new and existing users to customize their authentication experience. This can be done using the Condition option. Click the + button and select Condition to open a dialog for configuring an If-Else check. Set the step name to New/Existing User. In the If block, name it "New user" and use the authInfo.firstSeen key with the Is True operator to identify first-time logins. For the Else block, simply name it "Existing" since it automatically handles returning users. Save the condition to complete the setup:

Connect both Verify Code / OTP / Email and Sign Up or In / OAuth actions to the newly created condition so it performs the check every time a user logs in:

Next, a new screen, New user, needs to be added so that new users can provide their username and full name. To do this, create a new screen and add a Container element to the screen. Then inside the container, drag and drop the Display Name and Given Name inputs from the INPUTS section on the left panel. Also, add a button and change its text value to Continue. Remember to remove the screen body text element and save the new screen:

After creating the screen, you need to add an action to update the user's profile. Click the + button, select Action, and in the Actions dialog that appears, search for and select Update User / Attributes. Edit the action to map the input fields from the New user screen (form.displayName for Display Name and form.givenName for Given Name) to their corresponding user attributes, ensuring new users' profile information is properly stored:

Completing the flow

With the user detail collection screen and the update actions in place, you need to complete the flow by connecting these last two components. Start by connecting the New user screen's Submit button to the Update User / Attributes action, which ensures that when new users submit their details, the information gets properly stored in their user profile. The flow then needs two distinct paths to completion. The first path connects the Update User / Attributes action to the END node, handling new users who have just provided their additional information. The second path connects the Existing branch from the New/Existing user condition directly to the END of the flow, creating a streamlined experience for returning users who don't need to provide additional details. These connections work together to create two separate journeys through the authentication flow—one that collects necessary information from first-time users and another that provides a faster route for those returning to your application.

Here is the final version of the flow you just created:

Save the flow and click the Run button to test run the flow directly on the Descope Console:

Understanding the PublishPro application

The starter application is a CMS that currently lacks any authentication or access control.

Here is the Webflow app. Currently, anyone, without signing in, can access the dashboard, see all articles in the system, and access creation, editing, deletion, and publishing features:

While the application includes a navigation bar with a Sign In button, it lacks any functionality since authentication isn't implemented. This unrestricted access highlights two key security needs: protecting the dashboard behind authentication and implementing different access levels for various user roles.

Implementing authentication

Now that the authentication flow is set up in Descope, let's integrate it into the CMS application. You need to add the Descope web component and implement the authentication logic.

Adding the required scripts

To start, let's add the required Descope scripts, Descope web component, and user profile widget scripts to the Head code section of the Webflow app. These scripts provide the core functionality for the authentication system and user profile management. On the Webflow dashboard, under the Custom code tab of the site's settings, add the following scripts:

<script async src="https://unpkg.com/@descope/web-component@latest/dist/index.js"></script>
<script async src="https://static.descope.com/npm/@descope/user-profile-widget@0.0.113/dist/index.js"></script>

Remember to save the changes by clicking the Save button to successfully add the scripts to the Webflow app:

Descope provides a list of widgets that you can easily integrate alongside your authentication code to manage users' sessions:

Click the Show Code button and select the Web Component option to see the sample code included in the preceding code snippet.

Adding authentication and user profile modals

Next, create a Code embed element for the authentication. You need two key components: an authentication modal and a user profile modal. These components handle user sign-in and profile management, respectively.

For the authentication modal, create it under the Body element and name it auth-modal:

<!-- Auth Modal -->
<div class="auth-modal">
  <div class="auth-container">
    <descope-wc
      project-id="YOUR_PROJECT_ID"
      flow-id="publishpro-auth-flow"
      theme="light"
    />
  </div>
</div>

Make sure to replace YOUR_PROJECT_ID with the project ID from your Descope Console:

Next, let's also create the user profile modal next to the Sign In button and name it user-profile:

<!-- Authenticated State -->
<div id="user-profile" class="user-profile">
  <span id="user-name" class="user-name"></span>
  <div
    id="profile-widget-container"
    class="profile-widget-container"
  >
    <descope-user-profile-widget
      project-id="YOUR_PROJECT_ID"
      widget-id="user-profile-widget"
      theme="light"
    />
  </div>
</div>

Remember to replace the YOUR_PROJECT_ID with your project ID as well here:

Since authentication is being implemented, the dashboard of the app should be visible only to authenticated users. Let's create a new Combo class named w-hide with style display: none !important to hide the dashboard from unauthorized users. Add this new class to the existing main_wrapper class as well as to the auth-modal and the user-profile modal:

Enhancing with custom styles

You can use the <style> tag to add custom styles for the modals and other utility classes created in the remaining part of the project. This includes styles for the auth-modal, user-profile, and widget-containers. Navigate back to the dashboard, check under the Custom code tab, and add the following CSS below the two <script> tags in the Head code section:

<style>
  .auth-modal {
    position: fixed;
    top: 0;
    left: 0;
    width: 100%;
    height: 100%;
    background-color: rgba(0, 0, 0, 0.5);
    display: flex;
    justify-content: center;
    align-items: center;
    z-index: 999;
  }

  .auth-container {
    background-color: #ffffff;
    padding: 20px;
    border-radius: 8px;
    box-shadow: 0 2px 10px rgba(0, 0, 0, 0.1);
  }

  .user-profile {
    display: flex;
    align-items: center;
    gap: 1rem;
  }

  .user-name {
    color: #ffffff;
    font-weight: 500;
  }

  /* Utility Classes */
  ._w-hide {
    display: none !important;
  }

  .user-profile {
    position: relative;
    display: flex;
    align-items: center;
    gap: 1rem;
  }

  .user-name {
    color: #ffffff;
    font-weight: 500;
    cursor: pointer;
    padding: 8px;
  }

  .user-name:hover {
    background-color: rgba(255, 255, 255, 0.1);
    border-radius: 4px;
  }

  .profile-widget-container {
    position: absolute;
    top: 100%;
    right: 0;
    margin-top: 8px;
    display: none;
    z-index: 1000;
  }

  /* Add some shadow and background to the widget */
  descope-user-profile-widget {
    background: white;
    border-radius: 8px;
    box-shadow: 0 4px 6px -1px rgba(0, 0, 0, 0.1),
      0 2px 4px -1px rgba(0, 0, 0, 0.06);
  }
</style>

Remember to click the Save button for the styles to take effect on the project:

Implementing custom authentication

Next, let's add custom authentication to your Webflow app. To do this, go to the Custom code tab, scroll down to the Footer code section, and paste the code before the closing </body> tag. Let's break this down into easy steps.

To begin, you need to wait for the DOM to be fully loaded. Then set up the necessary DOM elements and initialize event listeners:

<script async>
document.addEventListener('DOMContentLoaded', function () {
  // Get references to all the UI elements needed to be manipulated
  const authModal = document.querySelector('.auth-modal');
  const mainWrapper = document.querySelector('.main_wrapper');
  const signInButton = document.querySelector('.sign-in-btn');
  const userProfile = document.querySelector('.user-profile_container');
  const userName = document.getElementById('user-name');
  const profileWidgetContainer = document.getElementById('profile-widget-container');
  const sidebar = document.querySelector('.sidebar_wrapper');
  const dashboard = document.querySelector('.dashboard_wrapper');

  // Initialize Descope authentication components
  const authComponent = document.querySelector('descope-wc');
  authComponent.addEventListener('success', handleAuthSuccess);
  authComponent.addEventListener('error', handleAuthError);

  // Set up the profile widget with logout handling
  const profileWidget = document.querySelector('descope-user-profile-widget');
  profileWidget.logout = handleLogout;

This preceding initialization code ensures the app has access to all the necessary elements and sets up the Descope authentication component with its event listeners. Think of it as gathering all the tools before starting work.

Making the authentication interface interactive

Next, you need to handle user interactions with the authentication interface. This includes showing the login modal and managing the profile widget:

  // Show the auth modal when users click sign in
  signInButton.addEventListener('click', function () {
    authModal.classList.remove('_w-hide');
  });

  // Toggle the profile drop-down when users click their name
  userProfile.addEventListener('click', function() {
    if (profileWidgetContainer.style.display !== "block")
      profileWidgetContainer.style.display = "block";
    else
      profileWidgetContainer.style.display = "none";
  });

  // Handle returning from social login
  const urlParams = new URLSearchParams(window.location.search);
  const isDescopeOAuthReturn = urlParams.has("descope-login-flow");
  if (isDescopeOAuthReturn) {
    authModal.classList.remove("_w-hide");
  }

These event listeners create the interactive elements of the authentication system. The code responds to user actions like clicking the sign-in button or toggling their profile menu. You also handle the special case of users returning from the social login.

Managing user sessions

The heart of the authentication system lies in how successful logins, errors, and logouts are handled. The following functions manage the user's session and update the interface accordingly:

  function handleAuthSuccess(e) {
    const { refreshJwt, user } = e.detail;

    // Store the user's session data securely
    localStorage.setItem('DSR', refreshJwt);
    localStorage.setItem('user_data', JSON.stringify(user));

    const userDataString = localStorage.getItem('user_data');
    const userData = JSON.parse(userDataString);

    // Show authenticated UI
    authModal.classList.add('_w-hide');
    signInButton.classList.add('_w-hide');
    userProfile.classList.remove('_w-hide');
    sidebar.classList.remove('_w-hide');
    dashboard.classList.remove('_w-hide');
    mainWrapper.classList.remove('_w-hide');

    if (user.name) {
      userName.textContent = user.name;
      userName.title = "Click to manage profile";
    }

    window.location.reload();
  }

  function handleAuthError(err) {
    console.error('Auth Error:', err);
  }

  function handleLogout(error) {
    if (error) {
      console.error('Logout Error:', error);
      return;
    }

    // Clean up session data and refresh
    localStorage.removeItem('DSR');
    localStorage.removeItem('user_data');
    window.location.reload();
  }

When authentication succeeds, the app securely stores the user's session data and updates the UI to show they're logged in. If something goes wrong, it logs the error. The logout function cleans up by removing stored data and refreshing the page.

Finally, handle session persistence so users don't need to log in every time they visit:

  // Check if user already has a valid session
  const token = localStorage.getItem('DSR');
  const userDataString = localStorage.getItem('user_data');
  const payload = JSON.parse(atob(token.split('.')[1]));
  const expiration = payload.exp * 1000;

  if ((Date.now() < expiration) && userDataString) {
    const userData = JSON.parse(userDataString);

    authModal.classList.remove('_w-hide');
    signInButton.classList.add('_w-hide');
    signInButton.classList.add('_w-hide');
    userProfile.classList.remove('_w-hide');
    mainWrapper.classList.remove('_w-hide');

    if (userData.name) {
      userName.textContent = userData.name;
    }
  } else {
    localStorage.removeItem('DSR');
    localStorage.removeItem('user_data');
  }
});
</script>

This code checks for an existing session when the page loads. If found, it automatically restores the user's authenticated state without requiring them to log in again.

Testing the authentication

To test this implementation, you can either publish your app or use the Webflow preview feature. The code creates a seamless authentication experience where users can sign in, maintain their session across page loads, and safely sign out when needed:

Users can manage their profile through the profile widget that appears when clicking their name:

Implementing RBAC

With authentication in place, you can now implement RBAC to manage different user permissions within the CMS. The application defines two roles with distinct permissions: Writers can create and edit their own articles, and Editors have full access, including publishing and deleting articles.

Creating roles and permissions

To create the roles and permissions in the Descope Console, navigate initially to the Authorization section. Under the RBAC tab, locate the Permissions section in the right panel. You're creating four distinct permissions that represent the core actions in the CMS. Start by clicking + Permission to create CreateArticleDrafts—this fundamental permission enables users to create new article drafts in the system. When setting up this permission, include a clear description explaining its purpose, such as "Allows creation of new article drafts in the CMS."

Continue adding permissions by creating UpdateArticleDrafts, which controls the ability to edit existing drafts. Follow this with the DeleteArticleDrafts to manage article removal privileges and, finally, PublishArticleDrafts to control who can publish articles publicly. For each permission, take time to write a descriptive explanation that will help you and future administrators understand its intended use.

Once your permissions are in place, move to the Roles panel to establish the two key roles needed for the CMS. Begin with the Writer role by clicking + Role. Writers need the ability to create and modify content, so assign them the CreateArticleDrafts and UpdateArticleDrafts permissions. Include a description, like "Content creators who can write and edit drafts," to clearly define their responsibilities.

Next, create the Editor role, which requires more comprehensive access. Editors need oversight of the entire content lifecycle, so assign them all four permissions: CreateArticleDrafts, UpdateArticleDrafts, DeleteArticleDrafts, and PublishArticleDrafts. Add a description, such as "Content managers with full article control," to document their broader responsibilities.

Here's the Authorization page with RBAC set up:

This permission structure mirrors common editorial workflows where writers focus on content creation and editors manage the overall publication process. Writers can develop and refine content, while editors maintain quality control through their additional abilities to remove content and determine what gets published.

Assigning roles

Once you have created the roles, head over to the Users section and update the existing users by assigning them roles as you chose:

Let's modify the application to show or hide features based on user roles. Update the Footer code script to include the following permission-checking functionality:

function checkPermission(user, permission) {
  const hasEditorRole = user.roleNames &&
    user.roleNames.some(role =>
      role.toLowerCase() === 'editor'
    );
  const hasWriterRole = user.roleNames &&
    user.roleNames.some(role =>
      role.toLowerCase() === 'writer'
    );

  // Editor has all permissions
  if (hasEditorRole) {
    return true;
  }

  // Writer has create and update permissions
  if (hasWriterRole) {
    return ['create', 'update'].includes(permission);
  }

  return false;
}

When the checkPermission function is called, it checks the user's roles using case-insensitive comparison (toLowerCase()) and then makes permission decisions based on a simple rule: if the user is an editor, they can access everything; but if the user is a writer, they only get access to create and update actions. Any other role or permission combination results in no access being granted.

Implementing permissions

Now, you need to tell the application which UI elements should be restricted based on user roles. You do this by adding custom data attributes to the buttons. These attributes act like permission labels, telling the code which buttons should be visible to which users.

Open the Webflow Editor and navigate to the Settings tab in the right panel. For each button in the interface, you add the appropriate permission attribute based on its function. Add data-permission="update" to Edit buttons, data-permission="delete" to Delete buttons, and data-permission="publish" to Publish buttons. These attributes work with an updateUIBasedOnPermissions function to dynamically show or hide buttons based on the user's role:

Updating the UI

With that in place, you can update the UI based on the user's roles when they authenticate. To do so, let's create the updateUIBasedOnPermissions function by updating the Footer code script to include the following snippet:

function updateUIBasedOnPermissions(user) {
  const permissions = ['create', 'update', 'delete', 'publish'];

  permissions.forEach(permission => {
    const elements = document.querySelectorAll(`[data-permission="${permission}"]`);
    const shouldDisplay = checkPermission(user, permission);

    elements.forEach(element => {
      element.style.display = shouldDisplay ? 'inline-block' : 'none';
    });
  });

  if (user.roleNames) {
    const isEditor = user.roleNames.some(role => role.toLowerCase() === 'editor');
    const isWriter = user.roleNames.some(role => role.toLowerCase() === 'writer');

    document.querySelectorAll('[data-role="editor"]').forEach(element => {
      element.style.display = isEditor ? 'block' : 'none';
    });

    document.querySelectorAll('[data-role="writer"]').forEach(element => {
      element.style.display = isWriter ? 'block' : 'none';
    });
  }
}

The updateUIBasedOnPermissions function manages the visibility of UI elements based on a user's role and permissions by checking all elements with specific data attributes (data-permission and data-role) and showing or hiding them accordingly.

To ensure this function is called when a user successfully authenticates, update the handleAuthSuccess function as shown here:

function handleAuthSuccess(e) {
  const { refreshJwt, user } = e.detail;

  localStorage.setItem('DSR', refreshJwt);
  localStorage.setItem('user_data', JSON.stringify(user));

  const userDataString = localStorage.getItem('user_data');
  const userData = JSON.parse(userDataString);

  const userDataString = localStorage.getItem('user_data');
  const userData = JSON.parse(userDataString);

  // Update UI based on roles and permissions
  updateUIBasedOnPermissions(userData);

  // Show authenticated UI
  authModal.classList.add('_w-hide');
  signInButton.classList.add('_w-hide');
  userProfile.classList.remove('_w-hide');
  sidebar.classList.remove('_w-hide');
  dashboard.classList.remove('_w-hide');
  mainWrapper.classList.remove('_w-hide');

  if (user.name) {
    userName.textContent = user.name;
    userName.title = "Click to manage profile";
  }

  window.location.reload();
}

In addition, update the initial authentication check to include permission-based UI updates:

// Check auth state on load
const token = localStorage.getItem('DSR');
const userDataString = localStorage.getItem('user_data');
const payload = JSON.parse(atob(token.split('.')[1]));
const expiration = payload.exp * 1000;

if ((Date.now() < expiration) && userDataString) {
  const userData = JSON.parse(userDataString);

  // Update permissions
  updateUIBasedOnPermissions(userData);

  signInButton.classList.add('_w-hide');
  userProfile.classList.remove('_w-hide');
  sidebar.classList.remove('_w-hide');
  dashboard.classList.remove('_w-hide');
  mainWrapper.classList.remove('_w-hide');

  if (userData.name) {
    userName.textContent = userData.name;
  }
} else {
  localStorage.removeItem('DSR');
  localStorage.removeItem('user_data');
}

Updating the sidebar

Finally, you need to apply the permission system to the sidebar's Quick Actions buttons to ensure they follow the same role-based rules as the other interface elements. In the Webflow Editor, open the Settings panel for the New Articles button in the sidebar. Just as you did with the other buttons, add the data-permission="create" attribute to ensure only users with article-creation permissions can see this button.

The Analytics button requires a different approach since it's a feature specifically for editors. Open its Settings panel and add the data-role="editor" attribute. Using a role-based attribute here makes sense because analytics access is tied to the editor role itself rather than a specific permission.

These attribute additions connect the Quick Actions buttons to the permission-checking system built, ensuring consistent access control throughout the interface. When a user logs in, these buttons automatically show or hide based on their assigned role, just like the other UI elements:

The next step would be to implement these same permission checks on your backend API using one of the Descope SDKs, but that's beyond the scope of this tutorial since the focus is on the frontend implementation with Webflow.

Conclusion

In this tutorial, you transformed a basic CMS into a secure, role-aware application using the Descope authentication and authorization capabilities. What makes this implementation particularly powerful is how robust security features were achieved without complex backend code, making it perfect for Webflow applications. Through the Descope visual flow editor, you created a customized authentication flow that offers both email OTP and social login options, providing users with flexible, secure authentication methods.

The integration of the Descope web component and user profile widget, combined with RBAC, demonstrates how modern authentication can be implemented in Webflow applications without sacrificing security or user experience. This tutorial transforms a vulnerable Webflow app into a more secure CMS where content creators and editors can collaborate safely within their designated roles.

To stay up to date with more developer tutorials, subscribe to the Descope blog or follow us on LinkedIn.

Modernize Auth Without Changing Your Firebase Sessions

Mrunank Pawar — Mon, 13 Apr 2026 15:00:00 +0000

This blog was originally published on Descope.

If your app is built on Firebase, authentication tends to sit right at the center of everything. Firestore rules, Cloud Functions, Storage access, and even analytics all assume there's a valid Firebase user session.

At the same time, Firebase Auth can feel limiting once you want to go beyond basic email/password or simple social login. Adding things like passkeys, flexible MFA, or more nuanced sign-in and recovery flows usually means a lot of custom work — or compromises in UX.

Descope External Tokens is designed for exactly this situation. It lets you run Descope Flows natively in your app, then hand off to Firebase at the very end so you still end up with a real Firebase session.

In other words: Descope handles authentication while Firebase continues to power everything else in your app.

External Tokens 101

By using Descope External Tokens with Firebase, Descope is the place where authentication happens, and Firebase is the place where sessions are consumed.

The flow looks like this:

The user signs in using a Descope Flow (passwordless, social, passkeys, MFA — whatever you've defined).
When the Flow finishes successfully, Descope returns an externalToken. That token is a Firebase custom auth token, signed by Descope using your Firebase admin credentials.
Your app calls signInWithCustomToken with Firebase.
Firebase creates a normal session, just as if the user had signed in directly with Firebase Auth.
Once that's done, your app is "Firebase authenticated" in the usual way.

Why use External Tokens

This pattern is useful if:

You want to use Descope's auth flows and UI
You don't want redirects or awkward webviews
You already rely heavily on Firebase services
You don't want to rebuild your backend or security rules

You're not replacing Firebase, you're simply plugging Descope into it.

Setting up the Firebase External Token Connector

To generate Firebase custom tokens, Descope needs access to your Firebase project's service account. This is done through a Firebase External Token connector.

This integration allows you to continue using Firebase's services while replacing Firebase Auth with Descope Flows.

Configuring the connector in Descope

In the Descope Console, navigate to the Connectors page and create a new connector using the Firebase template. You'll be asked to provide:

Connector Name: A unique name to help distinguish this connector (especially useful if you have multiple Firebase projects or environments).
Connector Description: A short description explaining what the connector is used for.
Service Account private key: The JSON credentials from your Firebase project. This allows Descope to securely sign Firebase custom tokens.

Getting the Firebase service account JSON

To generate a service account key in Firebase:

Open the Firebase Console and select your project
Click the gear icon and go to Project settings
Open the Service Accounts tab
Click Generate new private key
Download the JSON file

Open the file and copy the entire contents, including the surrounding braces.

Back in the Descope Console, paste this JSON into the Service Account field of the Firebase connector configuration. After saving, use the Test button to confirm the credentials were added correctly.

At this point, the connector itself is fully configured.

Enabling the connector for External Tokens

Once the connector exists, it needs to be enabled for use in authentication flows.

Go to Project Settings in the Descope Console
Open the External Token section and enable External Tokens
Select the Firebase connector you just created

From this point on, Descope will automatically generate a Firebase custom token at the end of a successful flow.

What the authentication response looks like

After a user successfully completes a Descope Flow, the authentication response includes an externalToken field. This value is the Firebase custom token your app should exchange immediately.

Here's what an example response looks like:

{
  "cookieDomain": "",
  "cookieExpiration": 0,
  "cookieMaxAge": 0,
  "cookiePath": "/",
  "externalToken": "FIREBASE_TOKEN",
  "firstSeen": false,
  "idpResponse": null,
  "refreshJwt": "DESCOPE_REFRESH_TOKEN",
  "sessionExpiration": 1750879215,
  "sessionJwt": "DESCOPE_SESSION_TOKEN",
  "user": {}
}

A React web example

On the web, the integration is straightforward: run a Descope Flow, grab the external token, and pass it to Firebase.

Firebase setup

import { initializeApp } from "firebase/app";
import { getAuth } from "firebase/auth";

const firebaseConfig = {
  apiKey: "YOUR_API_KEY",
  authDomain: "YOUR_PROJECT.firebaseapp.com",
  projectId: "YOUR_PROJECT_ID",
  appId: "YOUR_APP_ID",
};

export const app = initializeApp(firebaseConfig);
export const auth = getAuth(app);

Running a Flow and creating a Firebase session

import { AuthProvider, Descope } from "@descope/react-sdk";
import { signInWithCustomToken } from "firebase/auth";
import { auth } from "./firebase";

export default function App() {
  const onSuccess = async (e: any) => {
    const externalToken = e?.detail?.externalToken;
    if (!externalToken) {
      throw new Error("Missing Firebase external token");
    }
    await signInWithCustomToken(auth, externalToken);
    console.log("Firebase user:", auth.currentUser?.uid);
  };

  return (
    <AuthProvider projectId="YOUR_DESCOPE_PROJECT_ID">
      <Descope
        flowId="YOUR_FLOW_ID"
        onSuccess={onSuccess}
        onError={(e) => console.error(e)}
      />
    </AuthProvider>
  );
}

At this point, Firestore rules, Storage access, and Functions all work exactly as they did before.

A React Native example

Note: The Descope React Native SDK does not currently support Expo. If you're using Expo, follow the Expo OIDC integration instead.

Install the SDK

npm install @descope/react-native-sdk

For iOS:

cd ios && pod install

Wrap your app

import { AuthProvider } from "@descope/react-native-sdk";

export default function AppRoot() {
  return (
    <AuthProvider projectId="YOUR_DESCOPE_PROJECT_ID">
      <App />
    </AuthProvider>
  );
}

Running a Flow and creating a Firebase session

import { FlowView, useSession } from "@descope/react-native-sdk";
import auth from "@react-native-firebase/auth";

function LoginScreen() {
  const { manageSession } = useSession();

  return (
    <FlowView
      flowOptions={{
        url: "https://auth.descope.io/login/YOUR_PROJECT_ID",
        androidOAuthNativeProvider: "google",
        iosOAuthNativeProvider: "apple",
      }}
      onSuccess={async (jwtResponse) => {
        // Save the Descope session
        await manageSession(jwtResponse);

        // Exchange the external token for a Firebase session
        const externalToken = jwtResponse.externalToken;
        await auth().signInWithCustomToken(externalToken);
      }}
      onError={(err) => console.error(err)}
    />
  );
}

After this runs:

Descope manages the auth session lifecycle
Firebase manages the infrastructure session
Your app can safely use both

Descope Auth, Firebase sessions

Descope External Tokens give you a practical way to modernize authentication without undoing the work you've already invested in Firebase. You can build richer, more flexible sign-in experiences using Descope Flows, while continuing to rely on Firebase for sessions, access control, and the rest of your backend.

The integration point is intentionally simple: authenticate with Descope, exchange the returned token with Firebase, and move on. There's no custom token service to maintain, no changes to your Firebase rules, and no need to rethink how your app is structured.

It's also worth noting that External Tokens aren't the only way to connect Descope and Firebase. If you prefer not to use signInWithCustomToken at all, Descope can also be configured as a federated OIDC identity provider for Firebase. In that setup, Firebase handles the session directly after an OIDC login — but the tradeoff is that the authentication flow includes an OIDC redirect.

Both approaches are valid. External Tokens are usually the better fit when you want a fully native, no-redirect experience, especially on mobile. OIDC federation can be a good option if redirects are acceptable and you want Firebase to remain the system that completes the sign-in.

Either way, Descope lets you evolve authentication independently of the rest of your Firebase stack: and that flexibility is often the biggest win.

Sign up for Descope to begin your drag & drop auth journey. Have questions about our platform? Book a demo with our auth experts.

Adding Authentication and Remote Support to a Local MCP Server

Mrunank Pawar — Fri, 10 Apr 2026 15:00:00 +0000

This blog was originally published on Descope.

Model Context Protocol (MCP) servers allow developers to connect large language models (LLMs) to external tools and resources through a standardized protocol. Some MCP servers are designed to run locally, often because they need to access resources that are in the same environment as the AI agent. Others are designed to run remotely, such as when exposing shared APIs, cloud-hosted tools, or team-wide services. Remote access is powerful, but without proper controls, it can easily become a security risk.

An unsecured MCP server exposed to the internet can be discovered by automated scanners, abused by unauthorized users, or even used to extract sensitive data from connected resources. Nevertheless, with proper authentication and authorization in place, remote MCP servers can unlock new collaboration models. Teams can share cloud-hosted tools and services, manage who can access which resources, and even integrate audit logs for compliance and observability. This makes MCP servers safer and more practical in enterprise or team-based environments.

In this guide, you'll learn how to take a local Playwright MCP server and make it remote-ready with authentication powered by Descope. You'll expose your server for secure remote access, add user authentication using Descope Flows, and implement role-based access control (RBAC) to ensure only authorized users can access sensitive tools.

Prerequisites

To complete this tutorial, you need the following:

A Descope account
Node.js v18+ installed on your local machine.
The assets ZIP folder downloaded and extracted. The folder includes a preprepared Descope flow that you will use later in this guide.
A code editor and a web browser.

Preparing the local MCP server

The Playwright MCP server exposes a set of tools that let LLMs interact with Playwright to perform actions such as running browser tests, inspecting pages, taking screenshots, and more. For example, you can use it to build an AI agent that automates quality assurance by navigating to a web application, filling out forms, and verifying that the UI behaves correctly. These tasks otherwise require manual testing or complex custom scripts.

When running locally, the Playwright MCP server is accessible only from your own machine. This is ideal for initial development and testing as there's no risk of unauthorized access. However, if you want to expose this server remotely, for example, to integrate it into a cloud-based workflow or share it with your team, you need to make it accessible over the internet. This is where you need to start thinking about security; anyone who invokes the server's URL can invoke its tools and potentially run arbitrary browser automation on your infrastructure.

Let's go ahead and set up the Playwright MCP server locally. Start by creating a new project folder and initializing a Node.js project:

mkdir descope-playwright-mcp-auth
cd descope-playwright-mcp-auth
npm init -y

Install the Playwright MCP server, which is offered as an npm package by Microsoft:

npm install @playwright/mcp

Open the package.json file and replace the scripts section with the following content that provides a command to run the MCP server as a standalone server and adds the port flag to enable HTTP transport:

"scripts": {
  "start:mcp": "mcp-server-playwright --port 3001"
},

You can now run the Playwright MCP server by executing the following command in the terminal:

npm run start:mcp

You should get the following output:

> descope-playwright-mcp-auth@1.0.0 start:mcp
> mcp-server-playwright --port 3001

Listening on http://localhost:3001
Put this in your client config:
{
  "mcpServers": {
    "playwright": {
      "url": "http://localhost:3001/mcp"
    }
  }
}
For legacy SSE transport support, you can use the /sse endpoint instead.

To test that the Playwright MCP server is running as expected, you can use MCP Inspector. The MCP Inspector is a browser-based debugging tool that lets you interact with MCP servers without writing any client code. It's perfect for quickly verifying that your server is exposing the right tools and responding correctly before integrating it with an actual AI agent. On a separate terminal, execute the following command to start the MCP Inspector:

npx @modelcontextprotocol/inspector@0.17.2 --transport http --server-url http://localhost:3001/mcp

The --transport flag specifies how the client communicates with the MCP server. MCP supports three transport types: http (streamable HTTP), sse (server-sent events (SSE) for streaming), and stdio (standard input/output for local processes). Since the Playwright MCP server is running as an HTTP server on port 3001, you're using the http transport to connect to it.

This opens a browser tab where you can see the MCP Inspector interface. On the interface, select the Connect button to connect to your MCP server:

Once you're connected, you can perform actions such as listing the tools or invoking them:

Making the MCP server remote-capable

So far, the Playwright MCP server is listening on localhost:3001, which means it's accessible only from your own machine. No external connections can reach it because it's bound to localhost (127.0.0.1). This isolation makes it safe for local testing, but it also means teammates can't connect or share the same tools. To enable collaboration, you need to expose it over the network, but doing so requires proper authentication and authorization to prevent unauthorized access.

There are several approaches you can use to make the MCP server remotely accessible:

Binding to all interfaces (--host 0.0.0.0) exposes your server directly to your network but offers no authentication.
Using an authentication proxy offers programmatic control over authentication and authorization.

For this guide, you will use the authentication proxy approach with Express. This gives you full control over authentication logic and RBAC. It also integrates well with the Descope MCP Express SDK, which is designed to allow you to easily add MCP specification-compliant authorization to your MCP server. The authentication proxy sits between clients and the MCP server, and validates every request before forwarding it.

Start by installing the required dependencies for the authentication proxy:

npm i express cors http-proxy @descope/mcp-express dotenv
npm i -D typescript @types/node @types/express @types/cors @types/http-proxy ts-node

Create a new file named .env to store your configuration and add the following:

AUTH_PROXY_PORT=3000
MCP_SERVER_PORT=3001

This defines the ports assigned to the Playwright MCP server and the authentication proxy.

Define your TypeScript configuration by creating a new file named tsconfig.json and add the following:

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "commonjs",
    "outDir": "./dist",
    "rootDir": "./src",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true
  }
}

To implement the proxy logic, create a new file named src/auth-proxy.ts and add the following:

import "dotenv/config";
import express from "express";
import cors from "cors";
import httpProxy from "http-proxy";

const app = express();
app.use(cors());

const AUTH_PROXY_PORT = process.env.AUTH_PROXY_PORT || 3000;
const MCP_SERVER_PORT = process.env.MCP_SERVER_PORT || 3001;

// Create proxy instance targeting the localhost-bound MCP server
const proxy = httpProxy.createProxyServer({
  target: `http://localhost:${MCP_SERVER_PORT}`,
  changeOrigin: true,
  ws: false,
});

// Handle proxy errors
proxy.on("error", (err, req, res) => {
  console.error("Proxy error:", err);
  try {
    (res as any).writeHead?.(500, { "Content-Type": "text/plain" });
    (res as any).end?.("Proxy error");
  } catch (e) {
    // Ignore if already closed
  }
});

// Proxy all /mcp requests
app.use("/mcp", (req: any, res: any) => {
  proxy.web(req, res);
});

app.listen(AUTH_PROXY_PORT, () => {
  console.log(`Server running on port ${AUTH_PROXY_PORT}`);
});

process.on("SIGINT", () => {
  console.log("Shutting down server...");
  process.exit();
});

This code sets up a simple Express proxy server that listens on port 3000 and forwards all /mcp requests to the local Playwright MCP server running on port 3001. It uses http-proxy for request forwarding, applies cors to allow cross-origin access, and includes basic error handling.

Note: Please note that this setup supports HTTP transport only. Clients attempting to use SSE via the /sse endpoint or WebSocket connections do not function with this configuration. Supporting SSE requires additional setup to handle streaming responses, and WebSocket support requires the ws proxy option enabled. For most remote MCP deployments, HTTP transport is sufficient and easier to secure.

To make sure that the proxy is working as expected, run the MCP server using the command npm run start:mcp. In a separate terminal, run the proxy server:

npx nodemon --exec 'ts-node' src/auth-proxy.ts

Note: The --exec ts-node flag explicitly tells nodemon to use ts-node to execute the TypeScript file.

Run the MCP Inspector:

npx @modelcontextprotocol/inspector@0.17.2 --transport http --server-url http://localhost:3000/mcp

Note: Note that the --server-url flag is now pointing to the proxy server.

Once the MCP Inspector interface launches, you should be able to connect to the MCP server, list tools, and invoke them.

At this stage, your MCP server is accessible to anyone who can reach the exposed host and port. There's no authentication, no encryption (TLS), and no request validation. This means that anyone can potentially connect to your MCP server and invoke any tool.

Introducing authentication with Descope

As you saw in the previous section, anyone who discovers your proxy server's URL can connect to your MCP server and invoke any available tool. In production or shared development environments, this opens doors to unauthorized access and abuse. For a Playwright MCP server, this can mean unauthorized users running browser automation on your infrastructure, executing scripts that capture sensitive data from your environment, or triggering resource-intensive operations that consume server resources. Without authentication, you have no control over who has access to your tools and no way to audit usage or attribute usage to specific users.

Descope simplifies securing your MCP server with its visual, low-code flow editor. Instead of writing authentication logic from scratch, you can build complete authentication flows through a drag-and-drop interface. These flows define the entire authentication journey, from the user sign-in method, multifactor authentication (MFA), consent screens for third-party client access, and the process when authentication fails or succeeds. This approach lets you implement enterprise-grade security in minutes rather than days, while maintaining full control over the authentication experience.

The primary step to implementing authentication with Descope is to create a project. On your Descope console, click the project drop-down on the top navigation pane, and select + Project:

On the Create project form, provide "descope-playwright-mcp-auth" as the name of the project and select Create:

Next, navigate to the Flows page from the sidebar and click the Import flow button:

Upload the mcp-auth-consent.json file from the assets you downloaded earlier. This opens the flow in the Flow editor:

This flow has been created using the Descope flow editor by dragging and dropping authentication components, such as the user.loggedIn condition, authentication screens, verification actions, and consent conditions, onto the canvas and connecting them to define authentication logic. You can build similar flows either from scratch or from a template and use the available components. This tutorial uses a preprepared flow that includes the auth logic and consent flow to save time, but feel free to explore the editor and customize it later.

The flow starts by checking if the user is logged in. If they're not, they are redirected to a screen where they can sign in using either an emailed one-time password (OTP) or Google single sign-on (SSO). Once logged in, the flow checks if the third-party application (the MCP client) has been authorized. If not, they're redirected to a screen where the scopes being requested by the app are displayed, and the user can choose whether to authorize the app or not.

With the auth and consent flow in place, you need to set up Dynamic Client Registration (DCR). This protocol allows third-party client applications to register themselves automatically with your Descope project, instead of being manually preconfigured. When an MCP client, like the MCP connector, connects to your MCP server, it automatically initiates the DCR process by sending a registration request to the proxy's /oauth/register endpoint (provided by the Descope MCP Express SDK). The proxy handles the client registration, creates OAuth credentials for the client, and returns them so the client can proceed with authentication. All this happens behind the scenes. The MCP Inspector takes care of the DCR flow automatically once you point it to your proxy's URL, which is why you don't see explicit DCR code in the client implementation.

To set up DCR, navigate to the Inbound Apps page on your Descope console and select DCR Settings:

On the DCR Settings page, toggle the switch to enable DCR; and in the Approved scopes list section, provide the following:

Name: "openid"
Description: "Allows this app to confirm your identity and access basic profile information, such as your assigned roles."
Mandatory: Toggle to make sure this scope is mandatory

Next, scroll down to the User consent flow section, and in the Consent flow drop-down, select the flow you imported in the previous steps and save the settings:

Now that the DCR is configured, you need to obtain credentials that your proxy server uses to communicate with the Descope APIs. The proxy needs these credentials to validate tokens, manage client registrations, and enforce authentication policies.

Start by obtaining the project ID, which identifies your Descope project and tells the proxy which project's authentication rules to enforce. You can get this by navigating to the Project page:

You also need a management key to give your proxy server permission to perform administrative operations, like managing direct client registrations. Navigate to the Management Keys page, select + Management Key, and provide the key details by specifying the name and the roles:

Integrating Descope into the Playwright MCP server

At this point, you have completed setting up Descope. You enabled DCR so MCP clients can register automatically, configured the authentication and consent flow that users go through, and obtained credentials your proxy server needs to enforce authentication. The next step is to use these credentials to build the authentication proxy.

With your Descope project set up, you can now integrate authentication into the proxy. The goal is to make sure that every request is verified before it's proxied to the MCP server.

Before diving into the implementation, it's important to understand how the authentication flow works:

The MCP client, in this case, the MCP Inspector, registers with your proxy via the DCR.
You're redirected to the authentication/consent flow you set up earlier in Descope.
You log in and consent to the request scopes.
Descope issues an access token to the MCP client.
The MCP client includes this token in its requests to the proxy server.
The proxy server validates the token before forwarding the request to the MCP server.

To handle auth in the proxy, use the Descope MCP Express SDK you installed earlier. Start by adding the following to your .env file:

DESCOPE_PROJECT_ID=<YOUR-DESCOPE-PROJECT-ID>
DESCOPE_MANAGEMENT_KEY=<YOUR-DESCOPE-MANAGEMENT-KEY>
SERVER_URL=http://localhost:3000

The SERVER_URL ENV variable refers to the URL that exposes your MCP server; in this case, it's the proxy URL. Make sure to replace the placeholders for DESCOPE_PROJECT_ID and DESCOPE_MANAGEMENT_KEY with the values you obtained from your Descope console.

Next, open the src/auth-proxy.ts file and add the following imports:

import {
  descopeMcpAuthRouter,
  descopeMcpBearerAuth,
  DescopeMcpProvider,
} from "@descope/mcp-express";

Just below the MCP_SERVER_PORT definition, add the Descope MCP provider configuration:

const descopeProvider = new DescopeMcpProvider({
  projectId: process.env.DESCOPE_PROJECT_ID!,
  managementKey: process.env.DESCOPE_MANAGEMENT_KEY!,
  serverUrl: process.env.SERVER_URL!,
  dynamicClientRegistrationOptions: {
    authPageUrl: `https://api.descope.com/login/${process.env
      .DESCOPE_PROJECT_ID!}?flow=mcp-auth-consent`,
  },
});

// Add OAuth metadata and DCR endpoints
app.use(descopeMcpAuthRouter(undefined, descopeProvider));

// Protect your MCP endpoints with bearer authentication
app.use(["/mcp"], descopeMcpBearerAuth(descopeProvider));

This code initializes DescopeMcpProvider with your Descope project credentials and the proxy server URL. It also configures the DCR by specifying the URL to the auth and consent flow you set up earlier in the Descope console. The descopeMcpAuthRouter() function adds the required OAuth metadata endpoints and the DCR /register endpoint. The descopeMcpBearerAuth() function protects the specified endpoints by checking the incoming request for a bearer auth token and attaches the user information to req.auth.

Adding authorization to the Playwright MCP server

At this point, your proxy requires authentication but doesn't enforce RBAC, which restricts access to tools based on user roles. Authorization determines what authenticated users are allowed to do. For example, you may want to prevent regular users from installing browser binaries (which can consume significant resources or introduce security risks) while allowing admins full access to all tools.

For this guide, you'll use the already defined Tenant Admin role in Descope to represent a user with full access to all Playwright MCP tools. Only a user with this role can invoke the browser_install tool. In a production environment, you define custom roles and permissions that map to specific MCP tools or categories of tools. You maintain a configuration file or database that maps tool names to required roles and then check user roles against this mapping before allowing tool invocation. This tutorial uses a simple hard-coded check with a built-in Tenant Admin role to demonstrate the authorization pattern.

Start by adding the following import statement to the src/auth-proxy.ts file:

import { Readable } from "stream";

Next, add the following code before the line where you proxy /mcp requests:

app.use("/mcp", express.json(), async (req: any, res: any, next: any) => {
  // Only check authorization for POST requests with a body
  if (req.method == "POST" && req.body) {
    const mcpReq = req.body;

    // Check if the MCP method is a tools call
    if (mcpReq.method === "tools/call") {
      const toolName = mcpReq.params?.name;
      console.log(`Accessing tool: ${toolName}`);

      // If the tool is an admin tool, verify user has admin role
      if (toolName === "browser_install") {
        const authInfo = await descopeProvider.descope.validateJwt(
          req?.auth?.token!
        );
        const isAdmin = descopeProvider.descope.validateRoles(
          authInfo,
          ["Tenant Admin"]
        );

        if (!isAdmin) {
          console.log(
            `Unauthorized access attempt to admin tool: ${toolName}`
          );
          return res.status(403).json({
            jsonrpc: "2.0",
            error: {
              code: -32000,
              message: `Access denied: Tool '${toolName}' requires Tenant Admin role.`,
            },
            id: mcpReq.id || null,
          });
        }
      }
    }

    // Convert object back to string for the proxy
    req.body = JSON.stringify(mcpReq);
    req.headers["content-length"] = Buffer.byteLength(req.body).toString();
  }
  next();
});

This middleware intercepts all requests to the /mcp endpoint and uses express.json() to parse incoming JSON bodies so they can be inspected. The middleware specifically looks for tool invocation requests (identified by tools/call method) and checks the tool name against your authorization rules. For the restricted browser_install tool, it validates the user's JWT using the Descope SDK and ensures that they have the Tenant Admin role. Unauthorized requests are blocked with a 403 error, while valid requests continue through to the MCP server. The middleware reconstructs the request body and updates its headers so it can be properly proxied to the MCP server.

Finally, update the proxy handler to properly forward the reconstructed body:

app.use("/mcp", (req: any, res: any) => {
  proxy.web(req, res, {
    buffer: Readable.from([req.body ?? ""]),
  });
});

This code creates a readable stream from the reconstructed request body because the proxy library expects streaming data, not a plain string. After the middleware parses and potentially modifies the JSON body, you need to convert it back into a stream format that the proxy can forward to the upstream MCP server.

Your proxy now enforces both authentication and RBAC before forwarding requests to the MCP server.

Testing the integrations

You've set up authentication and authorization, so let's test that authenticated users can connect to your MCP server, unauthorized users are blocked, and RBAC properly restricts admin-only tools.

Start by running your local MCP server:

npm run start:mcp

In a separate terminal, run the auth proxy:

npx nodemon --exec 'ts-node' src/auth-proxy.ts

In another terminal, run the MCP Inspector:

npx @modelcontextprotocol/inspector@0.17.2 --transport http --server-url http://localhost:3000/mcp

Note: If you have another machine running on the network, you can run the MCP Inspector on it with the command npx @modelcontextprotocol/inspector@0.17.2 --transport http --server-url http://<AUTH-PROXY-MACHINE-IP>:3000/mcp, where <AUTH-PROXY-MACHINE-IP> is the IP address of the machine that is running both the MCP server and the auth proxy.

Once the MCP Inspector UI launches, select Connect to connect to your MCP server. You are then redirected to Descope to sign in:

Consent to the requested scopes:

Once you authorize the MCP client, you'll be connected to the MCP server:

At this point, if you try to invoke the browser_install tool, you will get an error that confirms RBAC is working as expected:

You now need to assign the user the Tenant Admin role to confirm that they can invoke the browser_install command if they have the appropriate roles. To do this, navigate to the Descope Users page and edit your user to assign them the Tenant Admin role:

Go back to the MCP Inspector UI, disconnect from the MCP server, and connect again. You are then prompted to sign in and consent to the requested scopes. Once you've done this, you can successfully invoke the browser_install command:

You can access the full code on GitHub.

Audit logging for compliance

For production environments, logging user activity is important for security monitoring and regulatory compliance. The current setup logs basic activity (such as tool access and authorization results) to the console. This is useful for local testing but not sufficient for production.

In a production environment, you should enhance this by doing the following:

Application-level logging: Capture detailed information about each request, including the timestamps, user IDs, roles, tools accessed, params used, and status of whether the request was granted. Send these logs to a centralized logging service, such as Amazon CloudWatch or Datadog, for long-term retention and analysis.
Descope audit logs: Descope automatically tracks all authentication events, login attempts, token generation, and role assignments. You can view these on the Audit page and export them for compliance reporting.
Compliance considerations: Different regulations (System and Organization Controls (SOC) 2 type 2, Health Insurance Portability and Accountability Act (HIPAA), General Data Protection Regulation (GDPR)) have specific requirements for log retention periods, tamper-proof storage, and access controls. Ensure your logging strategy aligns with your organization's compliance needs.

With proper audit logging, you gain full visibility into who is accessing your MCP server and what actions they're performing. As a result, you can quickly detect suspicious activity or unauthorized access attempts.

Conclusion

In this guide, you transformed a basic, local-only Playwright MCP server into a secure, remote-capable service. You learned how to upgrade from the default stdio transport to a remote-capable transport, expose it to remote connections through a proxy, protect it behind an authentication layer, and enforce fine-grained authorization using Descope.

Leaving an MCP server exposed without protection is a serious security risk. By adding authentication and authorization layers, you prevent unauthorized access while enabling collaborative, enterprise-grade workflows. This approach makes it possible for teams to connect to shared MCP servers with confidence that only approved users and roles can perform sensitive operations.

Descope provides purpose-built identity infrastructure for AI agents and MCP servers. Teams building external-facing MCP servers can add OAuth 2.1, PKCE, and secure DCR in three lines of code. Teams building AI agents can offload token management and storage for third-party tool connections. Teams building internal-facing MCP servers can implement policy-based AI agent access to corporate tools.

Whether you're building your first MCP server or scaling agentic workflows to production, Descope eliminates auth complexity so you can focus on building AI experiences. Explore Descope's AI-focused demos, check out the MCP documentation, or get started with a Free Forever account.