Dependents
A dependent is a user record for a family member who does not sign in with credentials of their own. Typical dependents are young children, or older relatives whom a caregiver looks after. A dependent belongs to exactly one family, and the family's guardians manage the dependent's data.
Many real families include people who cannot or should not authenticate. Before dependents existed, an app had two poor options for those people. It could invent an email address and push them through a sign-up flow, or store them in a separate database outside the identity layer. A dependent is a full Descope user, with a user ID, custom attributes, and audit history, but without its own login method.
How Dependents Differ from Regular Users
A dependent has a dependent flag on the user record, and it follows different rules from a regular user:
- One family: A dependent always belongs to exactly one family. The Allow multiple families per user setting does not apply to dependents.
- Generated login ID: Descope generates the dependent's login ID from the family ID and the dependent's name, unless you supply one. Descope never uses the dependent's email or phone as the login ID, because a dependent often shares those with a guardian.
- No invitation: Descope does not send an invitation to a dependent.
- Family limit: A dependent counts toward the family's maximum members.
The Console has no option to change a regular user into a dependent, or a dependent into a regular user. Create the user with the right type from the start.
Creating a Dependent
You create a dependent from the family it belongs to. In the Console, open the family from the Families page and go to Family Members.
Open the invite dialog
On the Family Members page, click the invite button.
Choose the dependent type
Select Dependent user. The dialog hides the invitation settings, because Descope does not invite dependents.
Enter the dependent's details
Enter a display name. The name is required, because Descope builds the login ID from it.
Review the generated login ID
Check the generated login ID in the disabled login ID field. Descope uses the format <family ID>-<display name>, in lowercase with hyphens for spaces. When Descope saves the dependent, it also removes punctuation from the name part, so the saved login ID can differ from the preview. For example, the display name "John Jr." becomes john-jr.
Set roles and attributes
Optionally, assign family roles and family-scoped attribute values, and then save.
The User or Dependent user choice appears only when you add members from a family's page. The invite dialog on the main Users page always creates a regular user.
From your backend, use Create Dependent in the management SDK. In a flow, use the create dependent flow action.
Finding Dependents
The Users page and each family's Family Members page have a Dependent column that shows whether each user is a dependent. On the Users page, the column is hidden by default, so turn it on from the table's column settings. You can filter the users table by this column, for example to list every dependent in the project.
From the SDK, pass the dependent filter to a user search.
Acting on Behalf of a Dependent
A dependent has no session of its own. When a guardian needs to use your app as the dependent, for example to book a child's appointment, the guardian impersonates the dependent. Descope issues a session for the dependent and records the guardian as the actor.
A guardian can impersonate a dependent only when both of these are true:
- The guardian belongs to the dependent's family.
- One of the guardian's family roles in that family has the Family Impersonate Dependents permission. The default Family Admin role has it.
The impersonation session has the dependent as sub, with the dependent's roles and tenants. The act claim holds the guardian's user ID, the same as in user impersonation. If you pass the family when you start the impersonation, the session's dcf claim also holds the family ID.
When the guardian finishes, stopping the impersonation gives the guardian a new session as themselves, with the guardian's original authentication methods and no act claim.
You can start and stop an impersonation in two places:
- In a flow: Use the impersonate and stop impersonation flow actions. The guardian is the user signed in to the flow.
- From your backend: Use Impersonate a Dependent and Stop Impersonating a Dependent in the management SDK.
Descope records each impersonation in the audit trail as a LoginSucceed event with the method FamilyImpersonate. The event's user is the dependent, and its actor is the guardian's user ID. Descope does not record the event when the dependent is a test user.
Deleting a Dependent
Deleting a dependent deletes the user record. From your backend, use Delete Dependent, which accepts only dependents and rejects a regular user.
Deleting the dependent's family does not delete the dependent. The dependent stays in your project with no family, and no guardian can act on its behalf. For details, see Disabling and Deleting Families.
Next Steps
To give guardians the right permissions, see Family Roles. To store per-family details about a dependent, see Family-Scoped Attributes.