Breached password detection is a critical component of secure applications.    Read the white paper

FusionAuth logo
FusionAuth logo
  • Features
    FusionAuth Reactor

    FusionAuth Reactor is a powerful suite of features developed to extend FusionAuth's core functionality.

    • Flexible Architecture   Flexible Architecture
    • Auth the Way You Want It   Auth the Way You Want It
    • Security & Compliance   Security & Compliance
    • Ultimate Password Control   Ultimate Password Control
    • Customizable User Experience   Customizable User Experience
    • Advanced Registration Forms   Advanced Registration Forms
    • Built for Devs   Built for Devs
    • User Management & Reporting   User Management & Reporting
    • Scalability   Scalability
    • Breached Password Detection   Breached Password Detection
    • Connectors   Connectors
    • FusionAuth Reactor   FusionAuth Reactor
  • Pricing
  • Docs
  • Downloads
  • Resources
    FusionAuth Resources
    • Upgrade from SaaS
    • Upgrade from Open Source
    • Upgrade from Home Grown
    • Blog   Blog
    • Forum   Forum
    • Community & Support   Community & Support
    • Customer & Partners   Customers & Partners
    • Video & Podcasts   Videos & Podcasts
    • Tech Guides   Getting Started
  • Expert Advice
    Expert Advice for Developers

    Learn everything you need to know about authentication, authorization, identity, and access management from our team of industry experts.

    • Authentication   Authentication
    • CIAM   CIAM
    • Identity Basics   Identity Basics
    • OAuth   OAuth
    • Security   Security
    • Tokens   Tokens
    • Dev Tools   Dev Tools
  • Account
Navigate to...
  • Welcome
  • Getting Started
  • 5-Minute Setup Guide
  • Reactor
  • Core Concepts
    • Overview
    • Users
    • Roles
    • Groups
    • Registrations
    • Applications
    • Tenants
    • Identity Providers
    • Authentication and Authorization
    • Integration Points
    • Roadmap
  • Installation Guide
    • Overview
    • System Requirements
    • Server Layout
    • Cluster
    • Docker
    • Fast Path
    • Kickstart™
    • Homebrew
    • Packages
    • Database
    • FusionAuth App
    • FusionAuth Search
    • Securing
    • Upgrading
  • APIs
    • Overview
    • Authentication
    • Errors
    • Actioning Users
    • Applications
    • Audit Logs
    • Connectors
      • Overview
      • Generic
      • LDAP
    • Consent
    • Emails
    • Event Logs
    • Families
    • Forms
    • Form Fields
    • Groups
    • Identity Providers
      • Overview
      • Apple
      • Facebook
      • Google
      • HYPR
      • Twitter
      • OpenID Connect
      • SAML v2
      • External JWT
    • Integrations
    • JWT
    • Keys
    • Lambdas
    • Login
    • Passwordless
    • Registrations
    • Reports
    • System
    • Tenants
    • Themes
    • Two Factor
    • Users
    • User Actions
    • User Action Reasons
    • User Comments
    • Webhooks
  • Client Libraries
    • Overview
    • Dart
    • Go
    • Java
    • JavaScript
    • .NET Core
    • Node
    • PHP
    • Python
    • Ruby
    • Typescript
  • Themes
    • Overview
    • Localization
    • Examples
  • Email & Templates
    • Overview
    • Configure Email
    • Email Templates
  • Events & Webhooks
    • Overview
    • Events
    • Writing a Webhook
    • Securing Webhooks
  • Example Apps
    • Overview
    • Go
    • Java
    • JavaScript
    • .NET Core
    • PHP
    • Python
    • Ruby
  • Lambdas
    • Overview
    • Apple Reconcile
    • External JWT Reconcile
    • Facebook Reconcile
    • Google Reconcile
    • HYPR Reconcile
    • JWT Populate
    • LDAP Connector Reconcile
    • OpenID Connect Reconcile
    • SAML v2 Populate
    • SAML v2 Reconcile
    • Twitter Reconcile
  • Identity Providers
    • Overview
    • Apple
    • Facebook
    • Google
    • HYPR
    • Twitter
    • OpenID Connect
      • Overview
      • Azure AD
      • Github
      • Discord
    • SAML v2
      • Overview
      • ADFS
    • External JWT
      • Overview
      • Example
  • Connectors
    • Overview
    • Generic Connector
    • LDAP Connector
    • FusionAuth Connector
  • Integrations
    • Overview
    • CleanSpeak
    • Kafka
    • Twilio
  • OpenID Connect & OAuth 2.0
    • Overview
    • Endpoints
    • Tokens
  • SAML v2 IdP
    • Overview
    • Google
    • Zendesk
  • Plugins
    • Writing a Plugin
    • Password Encryptors
  • Guides
    • Overview
    • Advanced Registration Forms
    • Breached Password Detection
    • Migration
    • Passwordless
    • Securing Your APIs
    • Silent Mode
  • Tutorials
    • Overview
    • Setup Wizard & First Login
    • Register/Login a User
    • Migrate Users
    • JSON Web Tokens
    • Authentication Tokens
    • Start and Stop FusionAuth
    • Switch Search Engines
    • User Account Lockout
    • Two Factor
  • Reference
    • CORS
    • Configuration
    • Data Types
    • Known Limitations
    • Password Encryptors
  • Release Notes
  • Troubleshooting

Family APIs

Overview

This API has been available since 1.7.0

A Family allows you to define relationships between one or more Users. A adult User may belong to a single Family, a teen or child may belong to one or more families.

The following APIs are provided to manage Families and Family memberships.

  • Add a User to a Family

  • Retrieve a Family

  • Update a Family

  • Remove a User from a Family

  • Retrieve Pending Family Members

  • Request Parental Approval

Add a User to a Family

This API is used to add a User to a Family. You cannot directly create a family, instead a family is implicitly created when the first User is added.

Request

Add a User to a Family with a randomly generated Id

URI

POST /api/user/family

Request Headers

X-FusionAuth-TenantId [String] Optional

The unique Id of the tenant used to scope this API request.

The tenant Id is not required on this request even when more than one tenant has been configured because the tenant can be identified based upon the request parameters or it is otherwise not required.

Specify a tenant Id on this request when you want to ensure the request is scoped to a specific tenant. The tenant Id may be provided through this header or by using a tenant locked API key to achieve the same result.

See Making an API request using a Tenant Id for additional information.

Add a User to a Family with the provided unique Id

URI

POST /api/user/family/{familyId}

Request Parameters

familyId [UUID] Optional defaults to secure random UUID

The Id to use for the new Family. If not specified a secure random UUID will be generated.

Request Headers

X-FusionAuth-TenantId [String] Optional

The unique Id of the tenant used to scope this API request.

The tenant Id is not required on this request even when more than one tenant has been configured because the tenant can be identified based upon the request parameters or it is otherwise not required.

Specify a tenant Id on this request when you want to ensure the request is scoped to a specific tenant. The tenant Id may be provided through this header or by using a tenant locked API key to achieve the same result.

See Making an API request using a Tenant Id for additional information.

Request Body

familyMember.userId [UUID] Required

The unique userId of the User to add to a family.

familyMember.owner [Boolean] Optional defaults to false

Set to true to indicate a family owner. This value will be ignored if the user role is Teen or Child.

familyMember.role [String] Required

The role of the user in the family. When creating a family the first user must be an Adult, this value must be set to Adult.

Example Request JSON
{
  "familyMember" : {
    "userId": "b3360a2d-e81d-4314-b9f1-244a916ca52f",
    "owner": true,
    "role": "Adult"
  }
}

Response

The response for this API contains the Family that was created.

Table 1. Response Codes
Code Description

200

The request was successful. The response will contain a JSON body.

400

The request was invalid and/or malformed. The response will contain an Errors JSON Object with the specific errors.

401

You did not supply a valid Authorization header. The header was omitted or your API key was not valid. The response will be empty. See Authentication.

500

There was an internal error. A stack trace is provided and logged in the FusionAuth log files. The response will be empty.

503

The search index is not available or encountered an exception so the request cannot be completed. The response will contain a JSON body.

Response Body

family.id [UUID]

The unique Id of the family.

families.insertInstant [Long]

The instant that the Family was added to the FusionAuth database.

families.lastUpdateInstant [Long]

The instant that the Family was updated in the FusionAuth database.

family.members [Array<Object>]

The members of this family.

family.members[x].insertInstant [Long]

The instant when the user was added to the family.

families.members[x].lastUpdateInstant [Long]

The instant when the family member was last updated.

family.members[x].owner [Boolean]

True if this user is the owner of the family, the first Adult user in the family will automatically be set as the owner. A teen or child cannot be the family owner.

family.members[x].role [String]

The role of the family member. The possible values are:

  • Adult

  • Child

  • Teen

family.members[x].userId [UUID]

The unique user Id of the family member.

Example Response JSON
{
  "family": {
    "id": "a815b480-d52d-4755-96ac-749c067925d7",
    "insertInstant": 1595361142909,
    "lastUpdateInstant": 1595361143101,
    "members": [
      {
        "insertInstant": 1562010348111,
        "lastUpdateInstant": 1595361143101,
        "owner": true,
        "role": "Adult",
        "userId": "b3360a2d-e81d-4314-b9f1-244a916ca52f"
      }
    ]
  }
}

Retrieve a Family

This API is used to retrieve a Family by a User Id or by Family Id.

Request

Retrieve a Family by Id

URI

GET /api/user/family/{familyId}

Request Parameters

familyId [UUID] Required

The unique Id of the Family.

Request Headers

X-FusionAuth-TenantId [String] Optional

The unique Id of the tenant used to scope this API request.

The tenant Id is not required on this request even when more than one tenant has been configured because the tenant can be identified based upon the request parameters or it is otherwise not required.

Specify a tenant Id on this request when you want to ensure the request is scoped to a specific tenant. The tenant Id may be provided through this header or by using a tenant locked API key to achieve the same result.

See Making an API request using a Tenant Id for additional information.

Request

Retrieve all of a User’s families by User Id

URI

GET /api/user/family?userId={userId}

Request Parameters

userId [UUID] Required

The unique Id of the User.

Request Headers

X-FusionAuth-TenantId [String] Optional

The unique Id of the tenant used to scope this API request.

The tenant Id is not required on this request even when more than one tenant has been configured because the tenant can be identified based upon the request parameters or it is otherwise not required.

Specify a tenant Id on this request when you want to ensure the request is scoped to a specific tenant. The tenant Id may be provided through this header or by using a tenant locked API key to achieve the same result.

See Making an API request using a Tenant Id for additional information.

The response for this API contains the requested family or families.

Table 2. Response Codes
Code Description

200

The request was successful. The response will contain a JSON body.

400

The request was invalid and/or malformed. The response will contain an Errors JSON Object with the specific errors.

401

You did not supply a valid Authorization header. The header was omitted or your API key was not valid. The response will be empty. See Authentication.

404

The object you requested doesn’t exist. The response will be empty.

500

There was an internal error. A stack trace is provided and logged in the FusionAuth log files. The response will be empty.

503

The search index is not available or encountered an exception so the request cannot be completed. The response will contain a JSON body.

Response Body

family.id [UUID]

The unique Id of the family.

families.insertInstant [Long]

The instant that the Family was added to the FusionAuth database.

families.lastUpdateInstant [Long]

The instant that the Family was updated in the FusionAuth database.

family.members [Array<Object>]

The members of this family.

family.members[x].insertInstant [Long]

The instant when the user was added to the family.

families.members[x].lastUpdateInstant [Long]

The instant when the family member was last updated.

family.members[x].owner [Boolean]

True if this user is the owner of the family, the first Adult user in the family will automatically be set as the owner. A teen or child cannot be the family owner.

family.members[x].role [String]

The role of the family member. The possible values are:

  • Adult

  • Child

  • Teen

family.members[x].userId [UUID]

The unique user Id of the family member.

Example Response JSON
{
  "family": {
    "id": "a815b480-d52d-4755-96ac-749c067925d7",
    "insertInstant": 1595361142909,
    "lastUpdateInstant": 1595361143101,
    "members": [
      {
        "insertInstant": 1562010348111,
        "lastUpdateInstant": 1595361143101,
        "owner": true,
        "role": "Adult",
        "userId": "b3360a2d-e81d-4314-b9f1-244a916ca52f"
      }
    ]
  }
}

Response Body

families [Array<Object>]

The list of Family objects.

families[x].id [UUID]

The unique Id of the family.

families[x].insertInstant [Long]

The instant that the Family was added to the FusionAuth database.

families[x].lastUpdateInstant [Long]

The instant that the Family was updated in the FusionAuth database.

families[x].members [Array<Object>]

The members of this family.

families[x].members[x].insertInstant [Long]

The instant when the user was added to the family.

families[x].members[x].lastUpdateInstant [Long]

The instant when the family member was last updated.

families[x].members[x].owner [Boolean]

True if this user is the owner of the family, the first Adult user in the family will automatically be set as the owner. A teen or child cannot be the family owner.

families[x].members[x].role [String]

The role of the family member. The possible values are:

  • Adult

  • Child

  • Teen

families[x].members[x].userId [UUID]

The unique user Id of the family member.

Example Response JSON
{
  "families": [
    {
      "id": "a815b480-d52d-4755-96ac-749c067925d7",
      "insertInstant": 1595361142909,
      "lastUpdateInstant": 1595361143101,
      "members": [
        {
          "insertInstant": 1562010348111,
          "lastUpdateInstant": 1595361143101,
          "owner": true,
          "role": "Adult",
          "userId": "b3360a2d-e81d-4314-b9f1-244a916ca52f"
        }
      ]
    }
  ]
}

Update a Family

This API is used to update an existing Family member. You may only update the User’s role or owner status.

Request

Update a Family member

URI

PUT /api/user/family/{familyId}

Request Parameters

familyId [UUID] Required

The unique Id of the Family.

Request Headers

X-FusionAuth-TenantId [String] Optional

The unique Id of the tenant used to scope this API request.

The tenant Id is not required on this request even when more than one tenant has been configured because the tenant can be identified based upon the request parameters or it is otherwise not required.

Specify a tenant Id on this request when you want to ensure the request is scoped to a specific tenant. The tenant Id may be provided through this header or by using a tenant locked API key to achieve the same result.

See Making an API request using a Tenant Id for additional information.

Request Body

familyMember.userId [UUID] Required

The unique userId of the User to add to a family.

familyMember.owner [Boolean] Optional defaults to false

Set to true to indicate a family owner. This value will be ignored if the user role is Teen or Child.

familyMember.role [String] Required

The role of the user in the family. The possible values are:

  • Adult

  • Child

  • Teen

Example Request JSON
{
  "familyMember" : {
    "userId": "b3360a2d-e81d-4314-b9f1-244a916ca52f",
    "owner": true,
    "role": "Adult"
  }
}

Response

The response for this API contains the Family that was updated.

Table 3. Response Codes
Code Description

200

The request was successful. The response will contain a JSON body.

400

The request was invalid and/or malformed. The response will contain an Errors JSON Object with the specific errors.

401

You did not supply a valid Authorization header. The header was omitted or your API key was not valid. The response will be empty. See Authentication.

404

The object you are trying to updated doesn’t exist. The response will be empty.

500

There was an internal error. A stack trace is provided and logged in the FusionAuth log files. The response will be empty.

503

The search index is not available or encountered an exception so the request cannot be completed. The response will contain a JSON body.

Response Body

family.id [UUID]

The unique Id of the family.

families.insertInstant [Long]

The instant that the Family was added to the FusionAuth database.

families.lastUpdateInstant [Long]

The instant that the Family was updated in the FusionAuth database.

family.members [Array<Object>]

The members of this family.

family.members[x].insertInstant [Long]

The instant when the user was added to the family.

families.members[x].lastUpdateInstant [Long]

The instant when the family member was last updated.

family.members[x].owner [Boolean]

True if this user is the owner of the family, the first Adult user in the family will automatically be set as the owner. A teen or child cannot be the family owner.

family.members[x].role [String]

The role of the family member. The possible values are:

  • Adult

  • Child

  • Teen

family.members[x].userId [UUID]

The unique user Id of the family member.

Example Response JSON
{
  "family": {
    "id": "a815b480-d52d-4755-96ac-749c067925d7",
    "insertInstant": 1595361142909,
    "lastUpdateInstant": 1595361143101,
    "members": [
      {
        "insertInstant": 1562010348111,
        "lastUpdateInstant": 1595361143101,
        "owner": true,
        "role": "Adult",
        "userId": "b3360a2d-e81d-4314-b9f1-244a916ca52f"
      }
    ]
  }
}

Remove a User from a Family

This API is used to remove a User from an existing Family.

Request

Remove a User from a Family

URI

DELETE /api/user/family/{familyId}/{userId}

Request Parameters

familyId [UUID] Required

The unique Id of the Family.

userId [UUID] Required

The unique Id of the User.

Request Headers

X-FusionAuth-TenantId [String] Optional

The unique Id of the tenant used to scope this API request.

The tenant Id is not required on this request even when more than one tenant has been configured because the tenant can be identified based upon the request parameters or it is otherwise not required.

Specify a tenant Id on this request when you want to ensure the request is scoped to a specific tenant. The tenant Id may be provided through this header or by using a tenant locked API key to achieve the same result.

See Making an API request using a Tenant Id for additional information.

Response

This API does not return a JSON response body.

Table 4. Response Codes
Code Description

200

The request was successful. The response will be empty.

400

The request was invalid and/or malformed. The response will contain an Errors JSON Object with the specific errors.

401

You did not supply a valid Authorization header. The header was omitted or your API key was not valid. The response will be empty. See Authentication.

404

The object you are trying to delete doesn’t exist. The response will be empty.

500

There was an internal error. A stack trace is provided and logged in the FusionAuth log files. The response will be empty.

503

The search index is not available or encountered an exception so the request cannot be completed. The response will contain a JSON body.

Retrieve Pending Family Members

This API is used to retrieve the users pending parent approval.

Request

Retrieve pending users by parent email address

URI

GET /api/user/family/pending?parentEmail={parentEmail}

Request Parameters

parentEmail [String] Required

The email address of the parent.

Request Headers

X-FusionAuth-TenantId [String] Optional

The unique Id of the tenant used to scope this API request.

The tenant Id is not required on this request even when more than one tenant has been configured because the tenant can be identified based upon the request parameters or it is otherwise not required.

Specify a tenant Id on this request when you want to ensure the request is scoped to a specific tenant. The tenant Id may be provided through this header or by using a tenant locked API key to achieve the same result.

See Making an API request using a Tenant Id for additional information.

Response

The response for this API contains the requested pending users.

Table 5. Response Codes
Code Description

200

The request was successful. The response will contain a JSON body.

400

The request was invalid and/or malformed. The response will contain an Errors JSON Object with the specific errors.

401

You did not supply a valid Authorization header. The header was omitted or your API key was not valid. The response will be empty. See Authentication.

404

The object you requested doesn’t exist. The response will be empty.

500

There was an internal error. A stack trace is provided and logged in the FusionAuth log files. The response will be empty.

503

The search index is not available or encountered an exception so the request cannot be completed. The response will contain a JSON body.

Response Body

users[x].active [Boolean]

True if the User is active. False if the User has been deactivated. Deactivated Users will not be able to login.

users[x].birthDate [String]

The User’s birthdate formatted as YYYY-MM-DD

users[x].data [Object]

An object that can hold any information about the User that should be persisted.

users[x].email [String]

The User’s email address.

users[x].fullName [String]

The User’s full name as a separate field that is not calculated from firstName and lastName.

users[x].id [UUID]

The User’s unique Id.

users[x].insertInstant [Long]

The instant when user was created.

users[x].parentEmail [String]

The user’s parent’s email address.

users[x].passwordChangeRequired [Boolean]

Indicates that the User’s password needs to be changed during their next login attempt.

users[x].passwordLastUpdateInstant [Long]

The instant that the User last changed their password.

users[x].preferredLanguages [Array<String>]

An array of locale strings that give, in order, the User’s preferred languages. These are important for email templates and other localizable text. See Locales.

users[x].tenantId [UUID]

The Id of the Tenant that this User belongs to.

users[x].timezone [String]

The User’s preferred timezone. This can be used as a default to display instants, and it is recommended that you allow User’s to change this per-session. The string will be in an IANA time zone format.

users[x].twoFactorDelivery [String]

The User’s preferred delivery for verification codes during a two factor login request.

The possible values are:

  • None

  • TextMessage

users[x].twoFactorEnabled [Boolean]

Determines if the User has two factor authentication enabled for their account or not.

users[x].username [String]

The username of the User.

users[x].usernameStatus [String]

The current status of the username. This is used if you are moderating usernames via CleanSpeak. The possible values are:

  • ACTIVE - the username is active

  • PENDING - the username is pending approval/moderation

  • REJECTED - the username was rejected during moderation

If a username has been rejected, it is still possible to allow the User to update it and have the new one moderated again.

users[x].verified [Boolean]

Whether or not the User’s email has been verified.

Example Response JSON
{
  "users" : [ {
    "active" : true,
    "birthDate" : "2009-10-31",
    "data" : {
      "attr1" : "value1",
      "attr2" : [ "value2", "value3" ]
    },
    "email" : "somekid@piedpiper.com",
    "fullName" : "Kid A",
    "id" : "00000000-0000-0001-0000-000000000003",
    "insertInstant" : 1572551641422,
    "parentEmail" : "somekidsparent@piedpiper.com",
    "passwordChangeRequired" : false,
    "passwordLastUpdateInstant" : 1572551641422,
    "preferredLanguages" : [ "en", "fr" ],
    "tenantId" : "64653766-6162-6234-3036-393935316533",
    "timezone" : "America/Denver",
    "twoFactorDelivery" : "None",
    "twoFactorEnabled" : false,
    "username" : "somekid",
    "usernameStatus" : "ACTIVE",
    "verified" : true
  } ]
}

Request Parental Approval

This API is used to send an email requesting parental approval for a child registration using the configured tenant.familyConfiguration.familyRequestEmailTemplateId.

Request

Request parental approval

URI

POST /api/user/family/request

Request Headers

X-FusionAuth-TenantId [String] Optional

The unique Id of the tenant used to scope this API request.

The tenant Id is not required on this request even when more than one tenant has been configured because the tenant can be identified based upon the request parameters or it is otherwise not required.

Specify a tenant Id on this request when you want to ensure the request is scoped to a specific tenant. The tenant Id may be provided through this header or by using a tenant locked API key to achieve the same result.

See Making an API request using a Tenant Id for additional information.

Request Body

parentEmail [String] Required

The email address of the parent.

Example Request JSON
{
  "parentEmail": "somekidsparent@piedpiper.com"
}

Response

This API does not return a JSON response body.

Table 6. Response Codes
Code Description

200

The request was successful. The response will contain a JSON body.

400

The request was invalid and/or malformed. The response will contain an Errors JSON Object with the specific errors.

401

You did not supply a valid Authorization header. The header was omitted or your API key was not valid. The response will be empty. See Authentication.

500

There was an internal error. A stack trace is provided and logged in the FusionAuth log files. The response will be empty.

503

The search index is not available or encountered an exception so the request cannot be completed. The response will contain a JSON body.

Quick Links

  • Download
  • Pricing
  • Enterprise Sales FAQ
  • Contact Us
  • Jobs (come work with us)
  • My Account

Resources

  • Docs
  • Blog
  • Community & Support
  • Upgrade from SaaS
  • Upgrade from Homegrown
  • Upgrade from Open Source

Everything Else

  • Privacy Policy
  • Product Privacy Policy
  • License
  • License FAQ
  • Security (contact, bug bounty, etc)
  • Technical Support

Connect with Us

logo
Subscribe for Updates
We only send dev friendly newsletters. No marketing fluff!
© 2020 FusionAuth