Skip to main content

Client-Initiated Account Linking

Client-initiated account linking enables AI agents to request access and connect to multiple identity providers on the user’s behalf through Auth0.

When a user authenticates with a supported identity provider, Auth0 creates a new identity associated with the connection in the user profile’s identities array. A user can have multiple identities associated with various identity providers.

Account linking is the process of linking multiple identities in a single user profile. As a result, users can log into supported identity providers with a single set of credentials instead of creating a separate user account for each identity provider. To learn more, read User account linking.

In Client-initiated account linking, the client initiates the account linking request to Auth0 on the user’s behalf. When the client attempts to access an external provider’s API that the user has not granted access to, Auth0 returns a response that it cannot find the access token for that service, triggering the account linking flow.

Pick Your Tech Stack

Coming soon!

Prerequisites

Before getting started, make sure you have completed the following steps:

unchecked

Create an Auth0 Account and a Dev Tenant

To continue with this quickstart, you need an Auth0 account and a Developer Tenant.

unchecked

Create Account Linking Application

Create and configure an Account Linking Application. To learn more about Auth0 Applications read ApplicationsArrow icon

unchecked

Add Account Linking Action

After you have created the Account Linking Application, create the Account linking Action. To learn more about Actions, read ActionsArrow icon

How it works​

Let’s walk through a real-world example: A user asks an AI agent integrated with a productivity app to fetch Google Calendar events:

  1. The application calls the Agent API with an Auth0 access token and the user input “Get Google Calendar events for today and tomorrow.”
  2. The Agent API uses an Auth0 access token to call Auth0 and requests a Google access token with the Calendar scopes.
  3. Auth0 looks for a Google access token with the requested Calendar scopes in the secure Token Vault. Because the user has not authorized access to the Google Calendar API, Auth0 returns a tokenset_not_found response.
  4. The Agent API returns this response to the application, which initiates an account linking request to Auth0.
  5. When the user authorizes access to the Google Calendar API, they also authorize Auth0 to perform the account linking flow.
  6. Auth0 then uses the Google access token to call the Google Calendar API and complete the operation.

When the primary user logs in via /authorize, the Client-Initiated Account Linking post-login Action checks for the link_account scope and attempts to link the requested user account (secondary account) with their existing logged in account (primary account).

To link user accounts, generate an authorize URL and pass the link_account scope along with the following parameters:

ParameterDescription
scopeSet to link_account to link accounts.
requested_connectionThe name of the connection you want to link accounts with.
requested_connection_scopeThe requested connection’s scopes.
id_token_hintThe ID token issued for the primary user.
// src/app/page.tsx
import { auth0 } from "@/lib/auth0";

async function generateAccountLinkingHref(requested_connection: string) {
  "use server";
  const session = await auth0.getSession();
  const id_token_hint = session!.tokenSet!.idToken!;
  const authParams = new URLSearchParams({
    scope: "link_account openid profile offline_access",
    requested_connection,
    id_token_hint,
  }).toString();

  return `/auth/login?${authParams}`;
}

export default async function Home() {
  return (
    <a href={await generateAccountLinkingHref("google-oauth2")}>
      Link Google Account
    </a>
  );
}

ctrl+C

When the account linking flow has been triggered:

  1. The Action checks if the user has a linked account for the requested connection by searching the user profile’s identities array. If a linked account for the requested connection already exists, the Action exits the account linking flow.
  2. The Action validates the ID token passed to id_token_hint by verifying that its sub claim matches the session's user ID. Note that the ID token shouldn’t be older than the expiration defined in the exp claim.
  3. After the Action determines that the currently logged-in user is the same user Auth0 is requesting account linking for, Auth0 validates that the user has access to the requested connection.
  4. The user authenticates with the requested connection by logging into their secondary account. If the secondary account requires MFA, the user authenticates with the configured MFA factor.
  5. Auth0 redirects back to the Action with the ID token from the secondary account authentication.
  6. After the Action validates the ID token, it uses Auth0 SDKs to link accounts into a single user profile. The secondary account is added to the user profile’s identities array.
  7. The Action sets the user ID back to that of the primary account. The user account linking flow completes and redirects the user back to your application.

To unlink accounts, use the Management API to call the Unlink a user account endpoint. To learn more, read Unlink user accounts.

ParameterDescription
scopeSet to link_account to link accounts.
requested_connectionThe name of the connection you want to link accounts with.
requested_connection_scopeThe requested connection’s scopes.
id_token_hintThe ID token issued for the primary user.

Learn more​