Junior Accounts

Junior accounts allow minors (users under a configurable age threshold) to participate on your platform under the supervision of a guardian. This guide explains how junior accounts work, how they differ from standard adult accounts, and what your integration needs to handle.

Postman Collection

For full request/response examples covering the junior account lifecycle, use the Postman collection:

Juniors Collection

Overview

A junior account is a special account type designed for minors. It differs from a standard account in several important ways:

• Username-based authentication -- Juniors log in with an alphanumeric username (e.g. junior123) and password, not an email address.
• Guardian supervision -- Every junior account is linked to a guardian's email address. The guardian receives verification emails and other communications on behalf of the junior.
• Restricted by default -- Junior accounts carry distinct roles and a minor_id field in their JWT, so your application can enforce age-appropriate restrictions.
• Upgradeable -- Once a junior reaches the configured age threshold (typically 16), they can upgrade to a full adult account.

Registration Flow

Registering a junior account requires the following information:

When a junior account is registered:

1. The account is created with a status of guardian_consent_required.
2. A verification email is sent -- either to the guardian or to the junior, depending on the client configuration.
3. The response includes tokens, but the status field will be guardian_consent_required rather than success, signaling that the account is not yet fully active.

Important: Your application should check the status field in the token response. If it is guardian_consent_required, you should inform the user that their guardian needs to verify the account before it is fully active.

Guardian Verification

Some clients have guardian verification enabled. When this is active, the flow works as follows:

• If the guardian already has a verified SSO account, a verification email is sent to the guardian asking them to consent to the junior's account.
• If the guardian has an unverified SSO account, a verification email is sent to the guardian first. Once the guardian verifies their own account, the junior verification email is then sent automatically.
• If the guardian does not have an SSO account, a "create account" email is sent to the guardian. They must register and verify before the junior account becomes active.

Once the guardian verifies, the junior account is assigned the ROLE_GUARDIANVERIFIED_* role.

Email Verification

• If the junior has their own email address, a separate verification email is sent to that address. Once verified, the junior receives the ROLE_VERIFIED_* role.
• If the junior does not have their own email, they receive the ROLE_VERIFIED_* role when the guardian verifies the account (since all communications go through the guardian).

In summary, a fully verified junior account (with guardian verification enabled) will have both ROLE_VERIFIED_* and ROLE_GUARDIANVERIFIED_*.

Authentication

Junior Login

Juniors authenticate using their username and password -- not an email address. The login grant type is the standard password grant, but with the username field containing the junior's alphanumeric username.

The token response for a junior login is structurally identical to an adult login, but the JWT payload contains additional junior-specific fields (see Roles and JWT below).

Guardian Login to Junior Account

A guardian can log in to one of their linked junior accounts without needing the junior's password. This uses the guardian's existing authenticated session:

1. The guardian must be logged in and have a verified email.
2. The guardian provides the junior's account_id (the junior's auth ID), their own refresh_token, and device_id.
3. The system validates that the junior is indeed linked to the guardian, then issues tokens for the junior's account.

This allows guardians to manage their junior's account or act on their behalf.

Roles and JWT

Junior-Specific JWT Claims

When a junior account is authenticated, the JWT contains additional fields that distinguish it from an adult account:

To determine if a user is a junior: check whether the minor_id claim is present and non-empty in the JWT. If it is, the user is a junior.

Roles

Junior accounts can have the following roles in the authorities array of the JWT:

Note: A junior account will not have ROLE_VERIFIED_* or ROLE_GUARDIANVERIFIED_* until the appropriate verification steps are complete. Your application should check for these roles if you need to gate features behind verified status.

Example JWT Payload (Decoded)

{
  "sub": 77112,
  "client_id": "YOURCLIENT",
  "first_name": "User",
  "email": "[email protected]",
  "email_verified": true,
  "minor_id": "junior123",
  "guardian_email": "[email protected]",
  "scope": ["open_id", "profile"],
  "authorities": [
    "ROLE_USER_*",
    "ROLE_VERIFIED_*",
    "ROLE_GUARDIANVERIFIED_*"
  ],
  "exp": 1613489775,
  "jti": "cd9c4b5b-d181-404c-8564-f40b3860bcf6",
  "iss": "InCrowd"
}

Note: The guardian_email claim may be absent if the guardian email is not set. Additional claims such as auth_time, sid, and entitlements may also be present depending on client configuration.

Account Upgrade

When a junior reaches the configured age threshold (default: 16 years old), they become eligible to upgrade to a full adult account. The age is validated against the date of birth stored in the user's profile.

How It Works

1. The junior (or their guardian) initiates an upgrade request and provides an email address for the new adult account.
2. The system verifies the junior's age by checking their date of birth in the profile service. If the junior is not old enough, the request is rejected.
3. The provided email must not already be in use by another account.
4. On success:
   • The minor_id and guardian_email fields are cleared from the account.
   • Junior-specific roles are removed, including ROLE_GUARDIANVERIFIED_*, ROLE_PROFILECOMPLETE_*, and ROLE_MARKETINGPREFERENCESCOMPLETE_*.
   • If the junior's email was not yet verified, ROLE_VERIFIED_* is also removed.
   • If the new email differs from the existing one, a verification email is sent and the account is marked as unverified until confirmed.
   • The user's profile is updated to reflect the upgrade.

After upgrading, the account behaves exactly like a standard adult account. The JWT will no longer contain the minor_id claim, and the user logs in with their email address instead of a username.

Important: The age threshold may vary by client. The default is 16, but this is configurable per client in the SSO configuration.

Linked Accounts

The linked accounts endpoint allows both guardians and juniors to discover their related accounts:

• For a guardian: returns a list of all junior accounts linked to their email address. Each entry includes the junior's id, first_name, last_name, email, minor_id (username), and account_type.
• For a junior: returns the guardian's account information (if the guardian has an SSO account), with the same fields.

Each linked account includes an account_type field:

• GUARDIAN -- the account is a guardian (returned when a junior queries their linked accounts).
• MINOR -- the account is a junior (returned when a guardian queries their linked accounts).

Restrictions

Junior accounts have inherent restrictions that your integration should account for:

• No email-based login -- Juniors cannot log in with an email address. Only the alphanumeric username is accepted.
• Guardian dependency -- All critical communications (password reset, verification) are routed through the guardian's email if the junior does not have their own email.
• Forgot password -- When a junior triggers a password reset, the reset email is sent to the guardian's email (or the junior's own email if one is set). The junior uses their username to initiate the flow.
• Third-party integrations -- Some external integrations may not support minor accounts. Your application should check for the minor_id claim in the JWT and handle these cases gracefully (e.g. displaying a message that a feature is unavailable for junior accounts).

Profile

Junior accounts interact with the profile service in the same way as adult accounts. Juniors can update their profile, and their profile data (including date of birth) is used for the age-based upgrade check.

When a junior upgrades to an adult account, the profile service is notified and updates the profile to reflect the new account type and email address.

Summary