Families

A family is a group of related users in a Descope project, such as a household with parents, children, and other caregivers. Each family has its own members, roles, and custom attributes, and a user can belong to a family without belonging to a tenant.

Consumer apps often serve people who act for someone else. A parent manages a child's account, or two separated parents share responsibility for the same child. A caregiver can also help an older relative. A model where every user is an independent account cannot represent those links. Apps used to keep relationship data in a separate store, or bend tenants to fit a household. Families put those relationships in the identity layer, next to the users they describe.

A good mental model: a family works like a tenant for a household. A user can belong to a family, hold family roles in it, and carry the family in their session token. Tenants work the same way. Families add two things that tenants do not have:

• Dependents: A dependent is a family member with no login credentials, such as a young child. A dependent belongs to exactly one family.
• Acting on behalf of a dependent: A guardian with the right family role can get a session as the dependent. Your app can then show and change the dependent's data. The session records the guardian as the actor, so your audit trail shows who acted.

Enabling Families

The family feature is off by default for every project. When families are off, the Console hides the Families page and the family flow actions. The family management APIs that change data return an error, but the APIs that read families and family settings still work.

To turn families on, open the Project Settings page and expand the Family Settings section on the General tab. Turn on Allow family capabilities and click Save. The Console then shows the other two family settings, and Families appears in the left navigation.

Turning families off later does not delete any families or memberships. Users keep their families in their session tokens.

Maximum Family Members

The Max users per family setting limits how many users one family can hold. Enter the limit in Number of members. The limit counts every member, including dependents. The minimum value is 1, and new projects start with a limit of 10.

Descope checks the limit each time a user joins a family, whether you add the user in the Console, through the SDKs, or in a flow. If the family is already full, Descope rejects the request and the user does not join.

Allowing Multiple Families per User

By default, a user can belong to only one family. Select Allow multiple families per user when the same person needs to be in more than one household.

The setting applies only to regular users. A dependent always belongs to exactly one family, whatever this setting says.

When this setting is off, Descope rejects any change that leaves a regular user in more than one family. Turning the setting off does not remove users who already belong to several families. Descope rejects any change to those users' families, including saving the edit user dialog, until the user is in one family.

Managing Families

Descope admins can create, edit, disable, activate, and delete families on the Families page of the Descope Console, or with the family management SDKs. The Families page works like the Tenants page: each row is one family, and you click a row to open that family's settings.

The families table has the following columns:

The table also has one column for each custom family attribute. You can search the table and filter it by its columns, for example to list every disabled family.

To create a family, click + Family. For the fields in the create dialog, refer to Creating a Family.

Disabling and Deleting Families

To change one family, click the three-dot menu in the family's row and select Edit, Disable or Activate, or Delete.

• Disable: Descope blocks guardian actions on the family until you activate it again. Guardians cannot add dependents through the SDKs or flows, and cannot act on behalf of a dependent. Users cannot select the family. You can still add and remove members and change their family roles.
• Activate: A disabled family becomes active again, and the blocked actions work as before.
• Delete: Descope deletes the family, and then removes every member from it and clears the members' family roles and family-scoped attribute values for it. Delete cannot be undone, so the Console asks you to type the family name to confirm.

Disabling a family does not disable its members. They can still sign in, and the family stays in their session tokens.

To act on several families at once, select their checkboxes in the table. The + Family button changes to Disable, Activate, and Delete buttons that apply to the whole selection. A batch delete asks you to type the number of selected families to confirm.

Custom Family Attributes

Custom family attributes store extra details about each family, such as the family's subscription plan. You manage them on the Custom Attributes tab of the Families page.

A custom family attribute can be of type text, numeric, boolean, single select, multi select, date, or month-day. Each attribute appears as a column in the families table and as a field when you create or edit a family.

A custom family attribute describes the family and has one value per family. To store a value that describes a user but differs from family to family, such as a child's nickname in each household, use a family-scoped attribute instead.

Family Permissions for Descopers

Two Descoper permission groups control who can work with families in the Console. Families View lets a Descoper view families and their settings, and Families Edit lets a Descoper manage them. Families Edit includes Families View.

The built-in Admin, Developer, and Support Descoper roles include both groups. The Auditor role includes only Families View. To give other Descopers access, add a family permission group to a custom Descoper role.

Families in Session Tokens

When a user belongs to families, Descope adds a families claim to the user's session token. The claim maps each family ID to the user's family roles and permissions in that family, in the same shape as the tenants claim. Your backend can read the claim to decide what a user can do in each family.

The families claim does not show whether a family is disabled. A disabled family stays in the claim with the same roles and permissions. If your backend must deny access in a disabled family, check the family's status with the family management SDKs instead of relying on the claim alone.

Like the tenants claim, Descope leaves out the families claim when your JWT template uses the Current Tenant, No Tenant Reference or No Descope Claims authorization claims format.

{
  "sub": "U2abc...",
  "families": {
    "smith-family": {
      "roles": ["Family Admin"],
      "permissions": ["Family Impersonate Dependents"]
    }
  },
  "dcf": "smith-family"
}

The dcf claim (Descope Current Family) holds the user's selected family. Descope keeps dcf when the session refreshes, and the refresh fails if the user has left that family. For the full claim list, see Token Claims Management.

Next Steps

After you turn families on, create and configure a family, then add dependents for members who do not sign in. To store a different user attribute value in each family, see family-scoped attributes.