Introduction

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 store data and give customized functionality to users. These users will still exist in the Descope Customer Identity and Access Management (CIAM) and can be treated like any other user account, meaning they’ll have associated refresh and session tokens and can be managed via the Descope console.

Types of users

1. Unknown: Not identified by Descope.
2. Anonymous: Identified in Descope via a random Login ID and password. Temporary, with a customizable but limited lifetime (eg. 1 year).
3. Regular: A user with a real Login ID in Descope. Deletable or disableable, but otherwise permanent.

Creating an Anonymous Account

1. Sign up a user with a random Login ID. Use a default password for all anonymous users. This password will be replaced with a random value in a later step.

{
  "user": {
    "loginIds": [
      "h89asdf@0ahsd8f.com"
    ],
    "userId": "U2beIJHbmK04QQ0saNqnNmOTOJiv",
    "name": "",
    "email": "",
    "phone": "",
    "verifiedEmail": false,
    "verifiedPhone": false,
    "roleNames": [],
    "userTenants": [],
    "status": "invited",
    "externalIds": [
      "h89asdf@0ahsd8f.com"
    ],
    "picture": "",
    "test": false,
    "customAttributes": {},
    "createdTime": 1706569043,
    "TOTP": false,
    "SAML": false,
    "OAuth": {},
    "webauthn": false,
    "password": false,
    "ssoAppIds": [],
    "givenName": "",
    "middleName": "",
    "familyName": ""
  }
}

2. For customized Anonymous User lifetimes, create a tenant called “Anonymous Users” and configure custom Session Management settings

3. Add tenant to user

Get the Anonymous Users Tenant ID from the previous step and update your user with this tenant. Now this user will have updated Session Management settings that differ from your general configuration.

4. Replace the password of the user with a random value. You will need your Login ID and default password from step 1. A response will be returned with the user’s JWTs like so:

{
  "sessionJwt": "XEqw34OVX13CajGLtOB-B-ejqkGrVMrwbPg1qXRkU7dfcZPzGI_2mt1SvCYTER1LytdyTxkUT_e07Ltfu7aPky8lsF0_kVbZb1hPPxkWjKv4X1o3_k6Ala4GV14HA...8a0dhsf0a8sdfasd0fhsd",
  "refreshJwt": "JH2sa6lvYwsM22GHfjCC38pe4s7GERNeKJnzKSEckg14PNVKWxP2atNjcQbG6fRZ-fLa7qUIA6evh06bh0K7gSX7Zg92MZoY1Aw_Je-kOf8NNcaENynnyQe-4LuDg...dh8asfoadsfasd8fh9asd",
  "cookieDomain": "",
  "cookiePath": "/",
  "cookieMaxAge": 31449599,
  "cookieExpiration": 1738019501,
  "user": {
    "loginIds": [
      "h89asdf@0ahsd8f.com"
    ],
    "userId": "U2beJAat53fihlCwfdFmXuuFjMIr",
    "name": "",
    "email": "h89asdf@0ahsd8f.com",
    "phone": "",
    "verifiedEmail": false,
    "verifiedPhone": false,
    "roleNames": [],
    "userTenants": [
      {
        "tenantId": "T2bVsGhoxoxSw306UcXsm5gibw5d",
        "roleNames": [],
        "tenantName": "Anonymous Users"
      }
    ],
    "status": "enabled",
    "externalIds": [
      "h89asdf@0ahsd8f.com"
    ],
    "picture": "",
    "test": false,
    "customAttributes": {},
    "createdTime": 1706569468,
    "TOTP": false,
    "SAML": false,
    "OAuth": {},
    "webauthn": false,
    "password": true,
    "ssoAppIds": [],
    "givenName": "",
    "middleName": "",
    "familyName": ""
  },
  "firstSeen": false
}

5. From the Replace Password response, you'll get the user’s Session and Refresh JWTs. Store them in the browser.

Convert Accounts to Regular

To convert accounts from Anonymous to Regular, a flow can be used where you add an identifier (eg phone, email) to an authenticated user.

When converting accounts to regular, 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.

Cull Accounts

Clear out old anonymous accounts that are never converted into regular user accounts. Synchronize this with the lifetime of the refresh token as set in your Session Management settings. You will need your own job to do this.

Using my own data store and ID generation

A benefit of handling anonymous accounts on your own is that they will not counted in my Descope Monthly Active User costs.

However, there are many benefits to using Descope Anonymous users:

• Converting to an account with real credentials will be easier since there is no data to move over
• All users managed in once place
• All users will have valid JWTs for backend requests