Anonymous Users

Anonymous Users allow applications to gradually build out user profiles without requiring identifying information like a phone number, email, or username. This is useful for scenarios where you don't want any registration friction but would like to rely on Descope as a Customer Identity Platform (CIAM) to issue a relevant access token and to manage the user's conversion to a regular user without loosing any user gathered data. Anonymous Users are identified with a unique Descope JWT type. Temporarily, with a lifetime that corresponds to the JWT's lifetime. Read more about utilizing Descope to boost conversions with anonymous users and guest checkout.

Creating an Anonymous User

Using the "Create Anonymous user - Add Information To JWT" flow template, we are given the basic ability to create the anonymous user's identity:

Eventually, the flow will create a token that we can use as the defined anonymous identity. Signed by Descope. This example shows an output of the flow where the "danu" claim is the indicator that this identity is in fact anonymous, and "displayName" as a custom claim that will help us inside our app:

// Payload:
{
  "danu": true,
  "displayName": "xxxxx",
  "drn": "DS",
  "exp": 1731843388,
  "iat": 1731842788,
  "iss": "xxxxxxxxx",
  "rexp": "2024-12-15T11:26:28Z",
  "sub": "xxxxxxxxx"
}
 
// Header:
{
  "alg": "RS256",
  "kid": "xxxxxxxxxxxxxxxx",
  "typ": "JWT"
}

Anonymous Users with SDK

You can use Descope management SDK for common user management operations like create user, update user, delete user, etc. The management SDK requires a management key, which can be generated here. Now, specifically for anonymous users, you will be generating a JWT token to define anonymity.

Install SDK

npm i --save @descope/node-sdk

Import and initialize Management SDK

import DescopeClient from '@descope/node-sdk';
 
const managementKey = "xxxx"
 
try{
    //  baseUrl="<URL>" // When initializing the Descope clientyou can also configure the baseUrl ex: https://auth.company.com  - this is useful when you utilize CNAME within your Descope project.
    const descopeClient = DescopeClient({ projectId: '__ProjectID__', managementKey: managementKey });
} catch (error) {
    // handle the error
    console.log("failed to initialize: " + error)
}
 
// Note that you can handle async operation failures and capture specific errors to customize errors.
//     An example can be found here: https://github.com/descope/node-sdk?tab=readme-ov-file#error-handling

Create an Anonymous User via SDK

This operation creates an anonymous user within the project with the details provided.

 // Args:
//  customClaims (Record<string, any>, optional): A dictionary of custom claims to include in the JWT.
//     These claims can be used to store additional user information.
//  selectedTenant (string, optional): The ID of the tenant to associate with the JWT.
//     This is useful for multi-tenant applications.
 
const customClaims = {
    role: "guest",
    permissions: ["read"]
};
 
const selectedTenant = "tenant_123";
 
const resp = await descopeClient.management.jwt.anonymous(customClaims, selectedTenant);
if (!resp.ok) {
    console.log("Failed to generate JWT for anonymous user.");
    console.log("Status Code: " + resp.code);
    console.log("Error Code: " + resp.error.errorCode);
    console.log("Error Description: " + resp.error.errorDescription);
    console.log("Error Message: " + resp.error.errorMessage);
} else {
    console.log("Successfully generated JWT for anonymous user.");
    console.log(resp.data);
}

Convert Accounts to Regular

As an example, to convert accounts from anonymous to regular, the "Sign up - Magic Link - Anonymous User Conversion" flow template can be used to convert and authenticate the user.

• This flow is a demonstration of a specific authentication method.
• Be sure to verify their Login ID with a real email or phone number. This prevents users from taking over accounts that have already been created that they do not own.