Download the PHP package descope/descope-php without Composer

by Descope

Overview

The Descope SDK for PHP provides convenient access to Descope authentication. You can read more on the Descope Website.

Getting started

Requirements

• PHP 7.3+

Installation

Install the package with Composer:

You'll need to set up a .env file in the root directory with your Descope Project ID, which you can get from the Console like this:

Using the SDK

In order to use the SDK you will need to initialize a DescopeSDK object with your Descope Project ID you defined in your .env file, like this:

Auth Management Key

Authentication methods whose public access has been disabled can still be used by providing an auth management key. When set, it is sent along with every authentication request.

Create one in the Descope Console with either the Authentication or Full Access scope on the project or company.

Note: the auth management key can, and probably should, be a different management key than the one provided as managementKey for management API usage. The auth management key is never sent on management requests, and the management key is never sent on authentication requests.

HTTP Timeouts

Every HTTP call the SDK makes is bounded so a slow or unresponsive network peer cannot hold a PHP worker indefinitely. By default each request times out after 60 seconds, with a 10 second connection-establishment timeout. Set requestTimeout (a positive number of seconds, may be fractional) to change the overall per-request deadline:

For full control over the transport (proxies, TLS, custom handlers, or your own timeout strategy) you can supply a pre-configured Guzzle-compatible client as httpClient. When you do, the SDK uses it as-is and does not apply its own timeout settings, so configure timeouts on the client itself:

Debug/Verbose Logging

The SDK supports optional debug/verbose logging to help troubleshoot API request issues. Debug logging is disabled by default to keep your application logs clean in production.

When enabled, the SDK will log detailed error information to PHP's error log (via error_log()) when API requests fail, including:

• HTTP status codes
• Error response bodies
• Request exceptions

You can enable debug logging in three ways:

1. Via Config Array (recommended):

2. Via Environment Variable:

   Then initialize the SDK normally (it will automatically detect the environment variable):

3. Via .env file:

Note: Debug logging uses PHP's error_log() function, so logs will appear in your configured PHP error log location (typically defined by error_log in php.ini or your server configuration).

Error Handling

When an API request fails (e.g. 4xx/5xx response, network error), the SDK throws exceptions instead of returning error arrays.

• Success: Methods return the decoded JSON response (or void where applicable).
• Failure: The SDK throws:
  • Descope\SDK\Exception\AuthException — for most request failures (bad request, unauthorized, server errors, etc.). The exception includes the HTTP status code, error type, and message (from the API when available).
  • Descope\SDK\Exception\RateLimitException — for HTTP 429 (rate limit) responses.

You can catch these and react accordingly:

The original Guzzle RequestException is available via $e->getPrevious() for logging or debugging.

Caching Mechanism

The Descope PHP SDK uses a caching mechanism to store frequently accessed data, such as JSON Web Key Sets (JWKs) for session token validation. 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.

By using the CacheInterface, you can integrate the Descope PHP SDK with any caching mechanism that suits your application, ensuring optimal performance in both small and large-scale deployments.

Custom Caching with CacheInterface

The SDK allows you to provide a custom caching mechanism by implementing the CacheInterface. This interface defines three methods that any cache implementation should support:

• get(string $key): Retrieve a value by key.
• set(string $key, $value, int $ttl = 3600): bool: Store a value with a specified time-to-live (TTL).
• delete(string $key): bool: Remove a value by key.

You can provide your custom caching implementation by creating a class that implements CacheInterface. Here's an example using Laravel's cache system:

To use the Laravel cache in the SDK:

Once you've configured your caching, you're ready to use the SDK. This SDK will easily allow you integrate Descope functionality with the following built-in functions:

Authentication Methods

Passwords

Sign Up

Sign In

Send Reset Password

Update Password

Replace Password

Get Password Policy

SSO

SSO Sign In

Exchange Token

OTP (One-Time Password)

The delivery method is one of "email", "sms", "whatsapp" or "voice".

Magic Link

Session Management

1. DescopeSDK->verify($sessionToken) - will validate the session token and return either TRUE or FALSE, depending on if the JWT is valid and expired.
2. DescopeSDK->refreshSession($refreshToken) - will refresh your session and return a new session token, with the refresh token.
3. DescopeSDK->verifyAndRefreshSession($sessionToken, $refreshToken) - will validate the session token and return either TRUE or FALSE, and will refresh your session and return a new session token.
4. DescopeSDK->logout($refreshToken) - will invalidate the refresh token and log the user out of the current session.
5. DescopeSDK->logoutAll($refreshToken) - will invalidate all refresh tokens associated with a given project, thereby signing out of all sessions across multiple applications.

6. DescopeSDK->getClaims($sessionToken) - will validate the JWT signature and return all of the verified claims in an array format.
7. DescopeSDK->getUserDetails($refreshToken) - will return all of the user information (email, phone, verification status, etc.) using a provided refresh token.
8. DescopeSDK->selectTenant($tenantId, $refreshToken) - will return a new set of tokens scoped to the selected tenant.
9. DescopeSDK->exchangeAccessKey($accessKey, $loginOptions) - will exchange an access key for a session JWT.
10. DescopeSDK->history($refreshToken) - will return the current user's authentication history.

User Management Functions

All management functions require a managementKey. That key is used only for management functions - to reach authentication methods whose public access has been disabled, use the Auth Management Key instead.

Each of these functions have code examples on how to use them.

Some of these values may be incorrect for your environment, they exist purely as an example for your own implementation.

Create User

Update User

Invite User

Batch Invite

Delete User

Search All Users

Add Tenant

Remove Tenant

Set Tenant Roles

Add Tenant Roles

Remove Tenant Roles

Set Temporary Password

Set Active Password

Logout User (Management)

Management (service-to-service) logout that terminates a user's sessions on all devices. This is distinct from the auth-side $descopeSDK->logout($refreshToken), which logs out the caller using their own refresh token. Use logoutUser to log out by login ID and logoutUserByUserId to log out by user ID.

Create Batch

Patch User

Patches a single user; only the non-null fields provided are updated.

Patch Batch

Delete Batch

Import Users

Load Users

Search All Test Users

Update Recovery Email / Phone

Custom Attribute Schema

Update User Names

Add Tenant Roles (append)

Passkeys

Remove TOTP Seed

Get Provider Token (with options)

Generate Embedded Link (Sign Up)

Trusted Devices

Tenant Management Functions

Manage tenants for multi-tenant applications.

Role Management Functions

Permission Management Functions

Access Key Management Functions

SSO Application Management Functions

Manage SSO (IdP) applications your project exposes to relying parties.

SSO Settings (Tenant SSO Configuration)

Configure the SSO provider used by a tenant. management->sso is the tenant SSO configuration component (distinct from the auth-flow $descopeSDK->sso).

JWT Management Functions

Flow & Theme Management Functions

Password Management

The SDK provides several classes for handling different types of passwords and password hashes. Here's how to use them:

Cleartext Passwords

For cleartext (plain text) passwords:

Hashed Passwords

The SDK supports multiple hash types. Here's how to use each:

BCrypt

SHA

MD5

PBKDF2

Django

Firebase

Outbound Apps

The SDK also supports Outbound Apps management via management->outboundApps. This allows you to fetch and manage user tokens for third-party outbound applications configured in Descope.

Fetch outbound app user token

Delete outbound app user tokens (by appId and/or userId)

Delete outbound app token by token id

Manage outbound applications

Fetch outbound app tokens

Upload outbound app tokens / API keys

Audit Management Functions

Unit Testing

The PHP directory includes unit testing using PHPUnit. You can insert values for session token and refresh tokens in the src/tests/DescopeSDKTest.php file, and run to validate whether or not the functions are operating properly.

To run the tests, run this command:

Running the PHP Sample App

In the sample/static/descope.js, replace the projectId with your Descope Project ID, which you can find in the Descope Console.

If you haven't already, make sure you run the composer command listed above, to install the necessary SDK packages.

Then, run this command from the root directory, to start the sample app:

The app should now be accessible at http://localhost:3000/ from your web browser.

This sample app showcases a Descope Flow using the WebJS SDK and PHP sessions to retain user information across multiple pages. It also showcases initializing the SDK and using it to validate the session token from formData sent from login.php.

Feedback

Contributing

We appreciate feedback and contribution to this repository!

Raise an issue

To provide feedback or report a bug, please raise an issue on our issue tracker.

This project is licensed under the MIT license. See the LICENSE file for more info.