HTML & PHP Quickstart

This is a quickstart guide to help you integrate Descope with your HTML & PHP application. Follow the steps below to get started.

Import SDK

You must import our WebJS and Web Component SDKs in order to use the Descope Flows component.

index.html

<!DOCTYPE html>
<html>
  <head>
	<script src="https://descopecdn.com/npm/@descope/web-component@x.x.x/dist/index.js"></script>
	<script src="https://descopecdn.com/npm/@descope/web-js-sdk@x.x.x/dist/index.umd.js"></script>
  </head>

  <body>
    <h1>Log In With Descope Flows</h1>
    <p id="container"></p>

	<script></script>
  </body>
</html>

Import Descope Functions and Add Flows Component

To trigger the Descope Flow, you will need to add this component. The screens you've customized in your Flow will appear here. You can also customize the component with the following:

flowId: ID of the flow you wish to use
onSuccess and onError: functions that execute when authentication succeeds or fails

Note

If you are using the autoRefresh token feature in the WebJS SDK, you will need to call sdk.refresh() in your onSuccess() function.

You can use the logic below to validate whether or not a user is logged in, before deciding to display the login flow. You can use the following parameters when initializing the SDK:

persistTokens: this will force existing tokens to be included in all outgoing requests
autoRefresh: this will automatically refresh sessions once they are expired, if the refresh token is valid

You should also make sure to add the base url, if you have a custom domain set up with your Descope project. This will ensure that your refresh tokens can be properly refreshed on the client side, pointing to the right URLs.

Note

For the full list of component customization options, refer to our Descope Components Doc.

index.html

<!DOCTYPE html>
<html>
  <head>
	<script src="https://descopecdn.com/npm/@descope/web-component@x.x.x/dist/index.js"></script>
	<script src="https://descopecdn.com/npm/@descope/web-js-sdk@x.x.x/dist/index.umd.js"></script>
  </head>

  <body>
	<h1>Log In With Descope Flows</h1>
    <p id="container"></p>

	<script>
		const sdk = Descope({ projectId: '__ProjectID__', baseUrl: '<base url>', persistTokens: true, autoRefresh: true });

		const sessionToken = sdk.getSessionToken()
		var notValidToken
		if (sessionToken) {
			notValidToken = sdk.isJwtExpired(sessionToken)
		}
		if (!sessionToken || notValidToken) {
			var container = document.getElementById('container');
			container.innerHTML = '<descope-wc project-id="__ProjectID__" base-url="<base url>" flow-id="sign-up-or-in"></descope-wc>';
			const wcElement = document.getElementsByTagName("descope-wc")[0];

			const onSuccess = (e) => {
				// You need to refresh the token here for auto refresh to work.
				sdk.refresh();
			};

			const onError = (err) => {
				// Print any errors to the console
				console.log(err);
			};

			// Add event listeners for onSuccess and onError
            wcElement.addEventListener('success', onSuccess)
            wcElement.addEventListener('error', onError)
		}
	</script>
  </body>
</html>

Optional Client Auth Settings

You can also customize client-side token behavior using optional parameters like persistTokens, and sessionTokenViaCookie. Learn more in the Auth Helpers documentation.

Make Sure Session Persists Across All Pages

On all of your frontend pages, you'll need to make sure that sdk.refresh() is called at the top of each page in <script> tags. Add the following logic to every authenticated page you have in your application.

index.html

<!DOCTYPE html>
<html>
  <head><!-- ... --></head>

  <body><!-- ... --></body>
</html>

<!-- Add below lines to all your authenticated pages -->
<script src="https://descopecdn.com/npm/@descope/web-js-sdk@x.x.x/dist/index.umd.js"></script>
<script>
  sdk.refresh()
  // Rest of your logic ...
</script>

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 here.

DESCOPE_PROJECT_ID=<Descope Project ID>
DESCOPE_MANAGEMENT_KEY=<Descope 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="https://api.descope.com") 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
    'baseUrl' => $_ENV['DESCOPE_BASE_URL'], // Optional, only used for custom domain or different regions
]);

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.

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
            exit();
        } else {
            error_log("Session token verification failed.");
            $descopeSDK->logout();

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

        // Redirect to login page
        exit();
    }

Checkpoint

Your application is now integrated with Descope. Please test with sign-up or sign-in use case.

Need help?

Customize

Now that you have the end-to-end application working, you can choose to configure and personalize many different areas of Descope, including your brand, style, custom user authentication journeys, etc. We recommend starting with customizing your user-facing screens, such as signup and login.

Customize

Was this helpful?

Checkpoint

On this page