Manage Users

The Firebase Admin Node.js 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.
  • Lookup users by different criteria such as email or uid.
  • 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.
  • 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 Node.js SDK, you must have a service account. Follow the setup instructions for more information on how to initialize the Admin Node.js SDK.

Retrieve user data

The primary way to identify a user is by their uid, a unique identifier for that user. You can pass this uid to the getUser() method to fetch that user's data:

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);
  });

The getUser() method returns a promise that is resolved with 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 promise returned by getUser() is rejected with 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. You can use the getUserByEmail() method to do the same lookup as above 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);
  });

As with the getUser() method above, the getUserByEmail() method returns a promise that is resolved with a UserRecord object for the user corresponding to the email provided to the method.

If the provided email does not belong to an existing user or the user cannot be fetched for any other reason, the promise returned by getUserByEmail() is rejected with an error. For a full list of error codes, including descriptions and resolution steps, see Admin Authentication API Errors.

Create a user

The createUser() method allows you to create a new Firebase Authentication user. The method accepts an object containing the UserRecord properties to use when creating the user:

Node.js

admin.auth().createUser({
  email: "user@example.com",
  emailVerified: false,
  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);
  });

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 in the object passed to createUser():

Node.js

admin.auth().createUser({
  uid: "some-uid",
  email: "user@example.com"
})
  .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);
  });

Any combination of the following properties can be provided:

Table 1. createUser() Properties

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.
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 createUser() method returns a promise fulfilled with a UserRecord object for the newly created user.

If the provided uid or email is already in use by an existing user or the user cannot be created for any other reason, the promise returned by createUser() is rejected with an error. For a full list of error codes, including descriptions and resolution steps, see Admin Authentication API Errors.

Update a user

The updateUser() method allows you to modify an existing user's data. It accepts a uid for the user to update as well as an object containing the UserRecord properties to update:

Node.js

admin.auth().updateUser(uid, {
  email: "modifiedUser@example.com",
  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);
  });

Any combination of the following properties can be provided:

Table 2. updateUser() Properties

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.
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 updateUser() method returns a promise fulfilled with an updated UserRecord object when the update successfully completes.

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

Delete a user

To delete an existing user, pass their uid to the deleteUser() method:

Node.js

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

The deleteUser() method returns an empty promise which is resolved if the deletion was successful.

If the provided uid does not correspond to an existing user or the user cannot be deleted for any other reason, the promise returned by deleteUser() is rejected with an error. 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.