Families with SDKs

If you want to learn more about families in general, see the Families page.

Descopers can manage families in the Descope Console, with the family management APIs, or with the management SDKs, as shown below. Family management is available in the Node.js, Python, and Go SDKs (Node.js SDK 2.18.0, Python SDK 2.15.0, and Go SDK 1.36.0 or later).

Family calls that change data fail until you turn families on for the project. Reading families and family settings still works. You can turn families on in the Console, as described in Enabling Families, or with Configure Family Settings below.

Family management using the management SDK

Backend SDK

Install SDK

Terminal

npm i --save @descope/node-sdk

Import and initialize SDK

import DescopeClient from '@descope/node-sdk';
try{
    //  baseUrl="<URL>" // When initializing the Descope client, you can also configure the baseUrl ex: https://auth.company.com  - this is useful when you utilize a custom domain within your Descope project.
    const descopeClient = DescopeClient({ projectId: '__ProjectID__' });
} catch (error) {
    // handle the error
    console.log("failed to initialize: " + error)
}

Load Family Settings

Use the code below to load the project's family settings. The settings say whether families are on, the maximum members in one family, and whether a user can join several families.

const resp = await descopeClient.management.family.getSettings();
if (!resp.ok) {
  console.log("Unable to load family settings.", resp.error);
} else {
  // { enabled, maxFamilyMembers, allowMultipleFamiliesUsers }
  console.log(resp.data);
}

Configure Family Settings

Use the code below to turn families on and set the family limits. Any setting you leave out keeps its current value. The maximum number of family members must be at least 1.

const resp = await descopeClient.management.family.configureSettings({
  enabled: true,
  maxFamilyMembers: 5,
  allowMultipleFamiliesUsers: false,
});
if (!resp.ok) {
  console.log("Unable to configure family settings.", resp.error);
}

Create Family

Use the code below to create a family. Descope generates the family ID unless you supply your own. The custom attributes must already be defined as custom family attributes.

// Args:
//    name (string): The family's name.
//    customAttributes (object, optional): Values for custom family attributes.
//    photo (string, optional): A URL for the family's photo.
//    disabled (boolean, optional): Create the family in a disabled state.
const resp = await descopeClient.management.family.create("Smith Family", { plan: "free" });
if (!resp.ok) {
  console.log("Unable to create family.", resp.error);
} else {
  console.log(resp.data.id);
}

// Or supply your own family ID:
const respWithId = await descopeClient.management.family.createWithId("smith-family", "Smith Family");
if (!respWithId.ok) {
  console.log("Unable to create family.", respWithId.error);
}

Update Family

Use the code below to update a family's name, photo, status, or custom attributes. Fields you leave out keep their current value. The custom attributes you pass replace the family's whole set of custom attribute values, so include every value you want to keep.

// Args: id, name?, customAttributes?, photo?, disabled?
const resp = await descopeClient.management.family.update("smith-family", "Smith Household", { plan: "premium" });
if (!resp.ok) {
  console.log("Unable to update family.", resp.error);
}

Delete Family

Use the code below to delete a family. This action is irreversible.

Deleting a family removes every member from it but does not delete the family's dependents. To remove them too, call Delete Dependent for each dependent first.

const resp = await descopeClient.management.family.delete("smith-family");
if (!resp.ok) {
  console.log("Unable to delete family.", resp.error);
}

Search Families

Use the code below to search the families in your project. You can filter by IDs, names, free text, and custom attribute values. A search with no filters returns every family. Pages start at 0, and a page holds at most 1,000 families.

// Options: ids?, names?, text?, customAttributes?, page?, size?
const resp = await descopeClient.management.family.searchAll({ customAttributes: { plan: "premium" } });
if (resp.ok) {
  resp.data.forEach((family) => console.log(family.id, family.name));
}

Create Dependent

Use the code below to add a dependent to a family. If you leave out the login ID, Descope derives one from the dependent's name. Descope never uses the dependent's email or phone as the login ID, because a dependent can share those with a guardian.

// Args:
//    familyId (string): The family the dependent belongs to.
//    options (object, optional): loginId, name, email, phone, givenName, middleName,
//      familyName, picture, customAttributes, familyScopedAttributes
const resp = await descopeClient.management.family.createDependent("smith-family", {
  name: "Max Smith",
  familyScopedAttributes: { nickname: "Maxie" },
});
if (resp.ok) {
  console.log(resp.data.userId, resp.data.loginIds);
}

Delete Dependent

Use the code below to delete a dependent by user ID. Descope finds the dependent's family from the user. To take a regular member out of a family without deleting the user, use Remove a User from Families instead.

const resp = await descopeClient.management.family.deleteDependent("dependent-user-id");

Impersonate a Dependent

Use the code below to get a session JWT that lets a family member act as a dependent. The impersonator must belong to the dependent's family and hold a family role with the Family Impersonate Dependents permission. If you pass a selected family, it must be the dependent's family.

When the guardian finishes, call Stop Impersonating a Dependent with the impersonation JWT to get the guardian's own session back.

The returned JWT has the dependent as sub and the guardian in the act claim. If you pass a selected family, the JWT also carries it in the dcf claim.

// Args:
//    impersonatorUserIdOrLoginId (string): The guardian acting for the dependent.
//    dependentLoginId (string): The dependent's login ID.
//    selectedFamily (string, optional): The dependent's family ID.
const resp = await descopeClient.management.family.impersonateDependent(
  "guardian@example.com",
  "dependent-login-id",
  "smith-family",
);
if (resp.ok) {
  const jwt = resp.data.jwt;
}

Stop Impersonating a Dependent

Use the code below to end an impersonation. Pass the impersonation JWT, and optionally custom claims and a refresh duration for the new session. The call returns a JWT for the guardian.

// Args: jwt, customClaims?, refreshDuration?
const resp = await descopeClient.management.family.stopImpersonation(impersonationJwt);
if (resp.ok) {
  const guardianJwt = resp.data.jwt;
}

Manage Custom Family Attributes

Use the code below to load, create, and delete the custom attribute definitions for families. Each call returns the full list of definitions after the change. The attribute type is a number: 1 text, 2 numeric, 3 boolean, 4 single select, 5 multi select, 6 date, and 7 month-day.

await descopeClient.management.family.createCustomAttributes([{ name: "plan", type: 1, displayName: "Plan" }]);
const attrs = await descopeClient.management.family.getCustomAttributes();
await descopeClient.management.family.deleteCustomAttributes(["plan"]);

Family members using the user management SDK

The user management SDK handles family membership for regular users. A family association names a family, the user's family roles in it, and the user's family-scoped attribute values for it.

Add a User to Families

Use the code below to add a user to one or more families. Adding merges with the user's current memberships: if the user already belongs to a family and you leave out roles or attribute values, the existing ones stay.

const resp = await descopeClient.management.user.addFamilies("guardian@example.com", [
  { familyId: "smith-family", roleNames: ["Family Admin"], familyScopedAttributes: { nickname: "Mom" } },
]);

Remove a User from Families

Use the code below to remove a user from one or more families. The user stays in your project.

const resp = await descopeClient.management.user.removeFamilies("guardian@example.com", ["smith-family"]);

Set Families When Creating, Inviting, or Updating a User

Use the code below to set a user's families as part of a create, invite, or update call. Pass a list of family associations in the user options.

Update replaces family memberships

An update call replaces the user's family memberships with the list you pass. A missing or empty list removes the user from every family. To update a dependent, include the dependent's family in the list.

To change other user fields without touching families, use a patch call instead. A patch call changes the user's families only when you pass family associations.

const resp = await descopeClient.management.user.create("guardian@example.com", {
  email: "guardian@example.com",
  familyAssociations: [
    { familyId: "smith-family", roleNames: ["Family Admin"], familyScopedAttributes: { nickname: "Mom" } },
  ],
});

The user objects that these calls return include two family fields. dependent says whether the user is a dependent. userFamilies lists each of the user's families with its familyId, roleNames, permissions, and familyScopedAttributes. In the Go SDK, the fields are Dependent and UserFamilies, and each UserFamily has FamilyID, Roles, Permissions, and FamilyScopedAttributes.

Search Users by Family

Use the code below to find the users in specific families, or to return only dependents or only regular users.

const resp = await descopeClient.management.user.search({ familyIds: ["smith-family"], dependent: true });

Manage Family-Scoped Attribute Definitions

Use the code below to load, create, and delete family-scoped attribute definitions. These calls live on the user management SDK because family-scoped attributes are user attributes. They take the same attribute types as custom family attributes.

await descopeClient.management.user.createFamilyScopedCustomAttributes([{ name: "nickname", type: 1 }]);
const attrs = await descopeClient.management.user.getFamilyScopedCustomAttributes();
await descopeClient.management.user.deleteFamilyScopedCustomAttributes(["nickname"]);

Next Steps

To run a complete example that creates a family, a guardian, and a dependent and then impersonates the dependent, see the examples/families folder in the Go SDK or Node.js SDK repository. For the Console side of the same tasks, see Configuring a Family.

Was this helpful?

On this page