Manage Users

The Firebase Admin SDK provides an API for managing your Firebase Authentication users with elevated privileges. The admin user management API gives you the ability to programmatically complete the following tasks from a secure server environment:

  • Create new users without any throttling or rate limiting.
  • Look up users by different criteria such as uid, email or phone number.
  • List all the users of a specified project in batches.
  • Access user metadata including account creation date and last sign-in date.
  • Delete users without requiring their existing password.
  • Update user properties - including their password - without having to sign in as the user.
  • Verify emails without having to go through the out-of-band action flows for verifying emails.
  • Change a user's email without sending email links to revoke these changes.
  • Create a new user with a phone number without having to go through the SMS verification flow.
  • Change a user's phone number without having to go through the SMS verification flow.
  • Offline provision users in a disabled state and then later control when to enable them.
  • Build custom user consoles that are tailored to a specific application's user management system.

Before you begin

To use the user management API provided by the Firebase Admin SDK, you must have a service account. Follow the setup instructions for more information on how to initialize the Admin SDK.

Retrieve user data

The primary way to identify a user is by their uid, a unique identifier for that user. The Admin SDK provides a method that allows fetching the profile information of users by their uid:

Node.js

admin.auth().getUser(uid)
  .then(function(userRecord) {
    // See the UserRecord reference doc for the contents of userRecord.
    console.log("Successfully fetched user data:", userRecord.toJSON());
  })
  .catch(function(error) {
    console.log("Error fetching user data:", error);
  });

Java

UserRecord userRecord = FirebaseAuth.getInstance().getUserAsync(uid).get();
// See the UserRecord reference doc for the contents of userRecord.
System.out.println("Successfully fetched user data: " + userRecord.getUid());

Python

from firebase_admin import auth

user = auth.get_user(uid)
print 'Successfully fetched user data: {0}'.format(user.uid)

This method returns a UserRecord object for the user corresponding to the uid provided to the method.

If the provided uid does not belong to an existing user or the user cannot be fetched for any other reason, the above method throws an error. For a full list of error codes, including descriptions and resolution steps, see Admin Auth API Errors.

In some cases you will have a user's email instead of their uid. The Firebase Admin SDK supports looking up user information with an email:

Node.js

admin.auth().getUserByEmail(email)
  .then(function(userRecord) {
    // See the UserRecord reference doc for the contents of userRecord.
    console.log("Successfully fetched user data:", userRecord.toJSON());
  })
  .catch(function(error) {
    console.log("Error fetching user data:", error);
  });

Java

UserRecord userRecord = FirebaseAuth.getInstance().getUserByEmailAsync(email).get();
// See the UserRecord reference doc for the contents of userRecord.
System.out.println("Successfully fetched user data: " + userRecord.getEmail());

Python

from firebase_admin import auth

user = auth.get_user_by_email(email)
print 'Successfully fetched user data: {0}'.format(user.uid)

This method returns a UserRecord object for the user corresponding to the email provided.

If the provided email does not belong to an existing user or the user cannot be fetched for any other reason, the Admin SDK throws an error. For a full list of error codes, including descriptions and resolution steps, see Admin Authentication API Errors.

In other cases, you will have a user's phone number instead of their uid. The Firebase Admin SDK supports looking up user information with a phone number:

Node.js

admin.auth().getUserByPhoneNumber(phoneNumber)
  .then(function(userRecord) {
    // See the UserRecord reference doc for the contents of userRecord.
    console.log("Successfully fetched user data:", userRecord.toJSON());
  })
  .catch(function(error) {
    console.log("Error fetching user data:", error);
  });

Java

UserRecord userRecord = FirebaseAuth.getInstance().getUserByPhoneNumberAsync(phoneNumber).get();
// See the UserRecord reference doc for the contents of userRecord.
System.out.println("Successfully fetched user data: " + userRecord.getPhoneNumber());

Python

from firebase_admin import auth

user = auth.get_user_by_phone_number(phone)
print 'Successfully fetched user data: {0}'.format(user.uid)

This method returns a UserRecord object for the user corresponding to the phone number provided.

If the provided phone number does not belong to an existing user or the user cannot be fetched for any other reason, the Admin SDK throws an error. For a full list of error codes, including descriptions and resolution steps, see Admin Authentication API Errors.

Create a user

The Admin SDK provides a method that allows you to create a new Firebase Authentication user. This method accepts an object containing the profile information to include in the newly created user account:

Node.js

admin.auth().createUser({
  email: "user@example.com",
  emailVerified: false,
  phoneNumber: "+11234567890",
  password: "secretPassword",
  displayName: "John Doe",
  photoURL: "http://www.example.com/12345678/photo.png",
  disabled: false
})
  .then(function(userRecord) {
    // See the UserRecord reference doc for the contents of userRecord.
    console.log("Successfully created new user:", userRecord.uid);
  })
  .catch(function(error) {
    console.log("Error creating new user:", error);
  });

Java

CreateRequest request = new CreateRequest()
    .setEmail("user@example.com")
    .setEmailVerified(false)
    .setPassword("secretPassword")
    .setPhoneNumber("+11234567890")
    .setDisplayName("John Doe")
    .setPhotoUrl("http://www.example.com/12345678/photo.png")
    .setDisabled(false);

UserRecord userRecord = FirebaseAuth.getInstance().createUserAsync(request).get();
System.out.println("Successfully created new user: " + userRecord.getUid());

Python

user = auth.create_user(
    email='user@example.com',
    email_verified=False,
    phone_number='+15555550100',
    password='secretPassword',
    display_name='John Doe',
    photo_url='http://www.example.com/12345678/photo.png',
    disabled=False)
print 'Sucessfully created new user: {0}'.format(user.uid)

By default, Firebase Authentication will generate a random uid for the new user. If you instead want to specify your own uid for the new user, you can include it argument passed to the user creation method:

Node.js

admin.auth().createUser({
  uid: "some-uid",
  email: "user@example.com",
  phoneNumber: "+11234567890"
})
  .then(function(userRecord) {
    // See the UserRecord reference doc for the contents of userRecord.
    console.log("Successfully created new user:", userRecord.uid);
  })
  .catch(function(error) {
    console.log("Error creating new user:", error);
  });

Java

CreateRequest request = new CreateRequest()
    .setUid("some-uid")
    .setEmail("user@example.com")
    .setPhoneNumber("+11234567890");

UserRecord userRecord = FirebaseAuth.getInstance().createUserAsync(request).get();
System.out.println("Successfully created new user: " + userRecord.getUid());

Python

user = auth.create_user(
    uid='some-uid', email='user@example.com', phone_number='+15555550100')
print 'Sucessfully created new user: {0}'.format(user.uid)

Any combination of the following properties can be provided:

Table 1. Properties supported by the create user operation

Property Type Description
uid string The uid to assign to the newly created user. Must be a string between 1 and 128 characters long, inclusive. If not provided, a random uid will be automatically generated.
email string The user's primary email. Must be a valid email address.
emailVerified boolean Whether or not the user's primary email is verified. If not provided, the default is false.
phoneNumber string The user's primary phone number. Must be a valid E.164 spec compliant phone number.
password string The user's raw, unhashed password. Must be at least six characters long.
displayName string The users' display name.
photoURL string The user's photo URL.
disabled boolean Whether or not the user is disabled. true for disabled; false for enabled. If not provided, the default is false.

The user creation method returns a UserRecord object for the newly created user.

If the provided uid, email or phone number is already in use by an existing user or the user cannot be created for any other reason, the above method fails with an error. For a full list of error codes, including descriptions and resolution steps, see Admin Authentication API Errors.

Update a user

The Firebase Admin SDK facilitates modifying an existing user's data. You need to specify a uid along with the properties to update for that user:

Node.js

admin.auth().updateUser(uid, {
  email: "modifiedUser@example.com",
  phoneNumber: "+11234567890",
  emailVerified: true,
  password: "newPassword",
  displayName: "Jane Doe",
  photoURL: "http://www.example.com/12345678/photo.png",
  disabled: true
})
  .then(function(userRecord) {
    // See the UserRecord reference doc for the contents of userRecord.
    console.log("Successfully updated user", userRecord.toJSON());
  })
  .catch(function(error) {
    console.log("Error updating user:", error);
  });

Java

UpdateRequest request = new UpdateRequest(uid)
    .setEmail("user@example.com")
    .setPhoneNumber("+11234567890")
    .setEmailVerified(true)
    .setPassword("newPassword")
    .setDisplayName("Jane Doe")
    .setPhotoUrl("http://www.example.com/12345678/photo.png")
    .setDisabled(true);

UserRecord userRecord = FirebaseAuth.getInstance().updateUserAsync(request).get();
System.out.println("Successfully updated user: " + userRecord.getUid());

Python

user = auth.update_user(
    uid,
    email='user@example.com',
    phone_number='+15555550100',
    email_verified=True,
    password='newPassword',
    display_name='John Doe',
    photo_url='http://www.example.com/12345678/photo.png',
    disabled=True)
print 'Sucessfully updated user: {0}'.format(user.uid)

Any combination of the following properties can be provided:

Table 2. Properties suported by the update user operation

Property Type Description
email string The user's new primary email. Must be a valid email address.
emailVerified boolean Whether or not the user's primary email is verified. If not provided, the default is false.
phoneNumber string The user's new primary phone number. Must be a valid E.164 spec compliant phone number. Set to null to clear the user's existing phone number.
password string The user's new raw, unhashed password. Must be at least six characters long.
displayName string | null The users' new display name. Set to null to clear the user's existing display name.
photoURL string | null The users' new photo URL. Set to null to clear the user's existing photo URL. If non-null, must be a valid URL.
disabled boolean Whether or not the user is disabled. true for disabled; false for enabled.

The update user method returns an updated UserRecord object when the update successfully completes.

If the provided uid does not correspond to an existing user, the provided email or phone number is already in use by an existing user, or the user cannot be updated for any other reason, the above method fails with an error. For a full list of error codes, including descriptions and resolution steps, see Admin Authentication API Errors.

Delete a user

The Firebase Admin SDK allows deleting existing users by their uid:

Node.js

admin.auth().deleteUser(uid)
  .then(function() {
    console.log("Successfully deleted user");
  })
  .catch(function(error) {
    console.log("Error deleting user:", error);
  });

Java

FirebaseAuth.getInstance().deleteUserAsync(uid).get();
System.out.println("Successfully deleted user.");

Python

auth.delete_user(uid)
print 'Successfully deleted user'

The delete user method returns an empty result when the deletion completes successfully.

If the provided uid does not correspond to an existing user or the user cannot be deleted for any other reason, the delete user method throws an error. For a full list of error codes, including descriptions and resolution steps, see Admin Authentication API Errors.

List all users

The Firebase Admin SDK allows retrieving the entire list of users in batches:

Node.js

function listAllUsers(nextPageToken) {
  // List batch of users, 1000 at a time.
  admin.auth().listUsers(1000, nextPageToken)
    .then(function(listUsersResult) {
      listUsersResult.users.forEach(function(userRecord) {
        console.log("user", userRecord.toJSON());
      });
      if (listUsersResult.pageToken) {
        // List next batch of users.
        listAllUsers(listUsersResult.pageToken)
      }
    })
    .catch(function(error) {
      console.log("Error listing users:", error);
    });
}
// Start listing users from the beginning, 1000 at a time.
listAllUsers();

Each batch of results contains a list of users and the next page token used to list the next batch of users. When all the users have already been listed, no pageToken is returned. This API also returns the passwordSalt and passwordHash hashed by the Firebase Auth backend if the user is a password user.

If no maxResults field is specified, the default 1000 users per batch is used. This is also the maximum number of users allowed to be listed at a time. Any value greater than the maximum will throw an argument error. If no pageToken is specified, the operation will list users from the beginning, ordered by creation time.

For a full list of error codes, including descriptions and resolution steps, see Admin Authentication API Errors.

Send feedback about...

Need help? Visit our support page.