PHP Quickstart

This guide will help you integrate Descope's PHP SDK into your backend application. The same SDK is also used with Laravel. Follow the steps below to get started.

Use this pre-built prompt to get started faster.

Install Backend SDK

Install the SDK with Composer using the following command:

Terminal

composer require descope/descope-php

Set up Environment file

Create a .env file in the root directory of your project with your Descope Project ID, which can be found in the Console

If you plan to use Management functions, include a Descope Management Key here as well, which can be found on the Company Settings Page of the console. The DESCOPE_AUTH_MANAGEMENT_KEY is only needed if your backend calls authentication methods whose API and SDK access is disabled.

.env

DESCOPE_PROJECT_ID=__ProjectID__
DESCOPE_MANAGEMENT_KEY=DESCOPE_MANAGEMENT_KEY
# Optional, only needed for authentication methods with API & SDK access disabled
DESCOPE_AUTH_MANAGEMENT_KEY=DESCOPE_AUTH_MANAGEMENT_KEY

Setup Backend SDK

You'll need to initialize a DescopeSDK object using your Project ID.

If you're using a custom domain with your Descope project, make sure to export the Base URL (e.g. export DESCOPE_BASE_URI="__BaseURL__") when initializing descope_client.

require 'vendor/autoload.php';
use Descope\SDK\DescopeSDK;

$descopeSDK = new DescopeSDK([
    'projectId' => $_ENV['DESCOPE_PROJECT_ID'],
    'managementKey' => $_ENV['DESCOPE_MANAGEMENT_KEY'], // Optional, only used for Management functions
    'authManagementKey' => $_ENV['DESCOPE_AUTH_MANAGEMENT_KEY'], // Optional, only needed for authentication methods with API & SDK access disabled
    'debug' => false, // Optional, logs failed API requests to your PHP error log (default: false)
    'requestTimeout' => 10, // Optional, seconds (default: 60)
]);

You can optionally configure the SDK's HTTP request timeout using requestTimeout, specified in seconds. It defaults to 60 seconds. The SDK also applies a fixed 10-second connection timeout when establishing HTTP connections.

Calling authentication methods with API & SDK access disabled

If you've set an authentication method's Trigger Method to Disable API & SDK, your backend can still call it by sending an auth management key with each authentication request. Create a separate management key with the Authentication role and pass it as authManagementKey, as shown above. The SDK doesn't read DESCOPE_AUTH_MANAGEMENT_KEY on its own, so you need to pass it in explicitly. See Restrict API and SDK Access to Authentication Methods for details.

Implement Session Validation

You will need to then fetch the session token from the Authorization header of each request, and use the SDK to validate the token.

The frontend SDK will store the session token in either a cookie or your browser's local storage. If using a cookie, the token will be sent to your app server automatically with every request.

Note

By default, the aud claim in your session token is your Descope Project ID. After verify() succeeds, check the claims (for example with getClaims) so you only accept tokens issued for your application.

You can change the audience in a JWT Template if you need a custom value.

The $descopeSDK->verify($sessionToken) function can be used to verify a user's session as shown below. This returns a TRUE or FALSE depending on if the JWT is valid or not.

if (isset($_POST["sessionToken"])) {
        if ($descopeSDK->verify($_POST["sessionToken"])) {
            $_SESSION["user"] = json_decode($_POST["userDetails"], true);
            $_SESSION["sessionToken"] = $_POST["sessionToken"];
            session_write_close();
    
            // User session validated and token saved
        } else {
            error_log("Session token verification failed.");
            $descopeSDK->logout();

            // Redirect to login page
        }
    } else {
        error_log("Session token is not set in POST request.");

        // Redirect to login page
    }

By default, the SDK uses APCu for caching, provided it is enabled and configured in your environment. If APCu is not available, and no other caching mechanism is provided, caching is disabled. Read about custom caching for the Descope SDK here.

The SDK can log failed API requests to your PHP error log to help you troubleshoot. Logging is disabled by default. Read about backend SDK logging to enable it.

Once you've implemented the basic session validation, you can enhance your application with these additional features:

User Management

Learn how to create, update, and manage users in your application.

Role-Based Access Control

Implement fine-grained access control using roles and permissions.

API Gateway Session Validation

Secure your API endpoints with session validation middleware.

Set up M2M Authentication

Implement M2M authentication with Descope.

Additional Resources

Have You Implemented the Frontend Yet?

When integrating Descope into your application, you have three options depending on how much control you want over your frontend authentication experience and session management:

Option	Description	Best For
Use Descope Flows	Design your authentication screens and flows visually in the Descope Console with little or no frontend code. We handle all session management for you.	Fastest setup with minimal custom frontend work.
Use Descope Client SDKs	Build your own login screens and authentication experiences in your frontend using code, while relying on Descope's SDKs to manage sessions (login, logout, refresh).	Customizable UX with simplified session handling.
Use Descope Backend SDKs	Build your own frontend and your own backend APIs for authentication. You fully manage sessions, tokens, and authentication logic yourself.	Maximum flexibility and control, at the cost of more engineering effort.

Descope Flows

Design login screens and authentication flows visually without writing code, and embed them into your app.

Descope Client SDKs

Build custom login screens in your frontend using code, while we manage session tokens and refreshing for you.

Was this helpful?