Unlink User Accounts

Learn how to use the Management API Unlink a User Account endpoint to unlink an identity from the target user account making it a separate user account again.

Use the Auth0 Management API Unlink a User Account endpoint or the Auth0.js library to unlink an identity from the target user account making it a separate user account again.

The result of the unlinking process is the following:

• The secondary account is removed from the identities array of the primary account.
• A new secondary user account is created.
• The secondary account will have no metadata.

If your goal is to delete the secondary identity entirely, you must first unlink the accounts, and then delete the newly created secondary account.

Depending on from where you call the endpoint, use one of these two scopes:

• update:current_user_identities from client-side code
• update:users from server-side code

The endpoint uses the following parameters:

Parameter	Type	Description
id	string	ID of the primary user account (required)
provider	string	identity provider name of the secondary linked account (e.g. google-oauth2)
user_id	string	ID of the secondary linked account (e.g. 123456789081523216417 part after the `

If your instance has users from multiple providers, you may also include [connection_name]| before the user_id stringto name the provider (for example, "user-id": "google-oauth2|123456789081523216417").

Response example

[
  {
    "connection": "Initial-Connection",
    "user_id": "5457edea1b8f22891a000004",
    "provider": "auth0",
    "isSocial": false,
    "access_token": "",
    "profileData": {
      "email": "",
      "email_verified": false,
      "name": "",
      "username": "johndoe",
      "given_name": "",
      "phone_number": "",
      "phone_verified": false,
      "family_name": ""
    }
  }
]

Use JWT from the primary account

To unlink accounts, call the Management API Unlink a User Account endpoint using the JWT from the primary account for authorization:

Use Access Token with the update:users scope

If you need to unlink two or more user accounts, call the Management API Unlink a User Account endpoint using an Management API Access Token with the update:users scope.

function unlinkAccount(secondaryProvider, secondaryUserId) {
  var primaryUserId = localStorage.getItem('user_id');
  var primaryAccessToken = localStorage.getItem('access_token');

  // Uses the Access Token of the primary user as a bearer token to identify the account
  // which will have the account unlinked to, and the user id of the secondary user, to identify
  // the user that will be unlinked from the primary account.

  $.ajax({
    type: 'DELETE',
    url: 'https://' + AUTH0_DOMAIN +'/api/v2/users/' + primaryUserId +
         '/identities/' + secondaryProvider + '/' + secondaryUserId,
    headers: {
      'Authorization': 'Bearer ' + primaryAccessToken
    }
  }).then(function(identities){
    alert('unlinked!');
    showLinkedAccounts(identities);
  }).fail(function(jqXHR){
    alert('Error unlinking Accounts: ' + jqXHR.status + ' ' + jqXHR.responseText);
  });
}

Unlink accounts from server-side code

1. Update the user in session with the new array of identities (each of which represent a separate user account).

const ensureLoggedIn = require('connect-ensure-login').ensureLoggedIn();
const Auth0Client = require('../Auth0Client');
const express = require('express');
const router = express.Router();
...
router.post('/unlink-accounts/:targetUserProvider/:targetUserId',ensureLoggedIn, (req,res,next) => {
  Auth0Client.unlinkAccounts(req.user.id, req.params.targetUserProvider, req.params.targetUserId)
  .then( identities => {
    req.user.identities = req.user._json.identities = identities;
    res.send(identities);
  })
  .catch( err => {
    console.log('Error unlinking accounts!',err);
    next(err);
  });
});

1. Call the Management API v2 Unlink a User Account endpoint using an Management API Access Token with the update:users scope.

Learn more

• Link User Accounts
• User Account Linking: Server-Side Implementation
• User-Initiated Account Linking: Client-Side Implementation