User management

The Firebase Admin SDK for PHP provides an API for managing your Firebase users with elevated privileges. The admin user management API gives you the ability to programmatically retrieve, create, update, and delete users without requiring a user’s existing credentials and without worrying about client-side rate limiting.

use Kreait\Firebase\Factory;

$auth = (new Factory)

User Records

UserRecord s returned by methods from the Kreait\Firebase\Auth class have the following signature:

    "uid": "jEazVdPDhqec0tnEOG7vM5wbDyU2",
    "email": "user@domain.tld",
    "emailVerified": true,
    "displayName": null,
    "photoUrl": null,
    "phoneNumber": null,
    "disabled": false,
    "metadata": {
        "createdAt": "2018-02-14T15:41:32+00:00",
        "lastLoginAt": "2018-02-14T15:41:32+00:00"
    "providerData": [
            "uid": "user@domain.tld",
            "displayName": null,
            "email": "user@domain.tld",
            "photoUrl": null,
            "providerId": "password",
            "phoneNumber": null
    "passwordHash": "UkVEQUNURUQ=",
    "customClaims": null,
    "tokensValidAfterTime": "2018-02-14T15:41:32+00:00"

List users

To enhance performance and prevent memory issues when retrieving a huge amount of users, this methods returns a Generator.

$users = $auth->listUsers($defaultMaxResults = 1000, $defaultBatchSize = 1000);

foreach ($users as $user) {
    /** @var \Kreait\Firebase\Auth\UserRecord $user */
    // ...
// or
array_map(function (\Kreait\Firebase\Auth\UserRecord $user) {
    // ...
}, iterator_to_array($users));

Get information about a specific user

$user = $auth->getUser('some-uid');
$user = $auth->getUserByEmail('user@domain.tld');
$user = $auth->getUserByPhoneNumber('+49-123-456789');

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:

$userProperties = [
    'email' => '',
    'emailVerified' => false,
    'phoneNumber' => '+15555550100',
    'password' => 'secretPassword',
    'displayName' => 'John Doe',
    'photoUrl' => '',
    'disabled' => false,

$createdUser = $auth->createUser($userProperties);

// This is equivalent to:

$request = \Kreait\Auth\Request\CreateUser::new()
    ->withDisplayName('John Doe')

$createdUser = $auth->createUser($request);

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 in the properties passed to the user creation method:

$properties = [
    'uid' => 'some-uid',
    // other properties

$request = \Kreait\Auth\Request\CreateUser::new()
    // with other properties

Any combination of the following properties can be provided:

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.


All of the above properties are optional. If a certain property is not specified, the value for that property will be empty unless a default is mentioned in the above table.


If you provide none of the properties, an anonymous user will be created.

Update a user

Updating a user works exactly as creating a new user, except that the uid property is required:

$uid = 'some-uid';
$properties = [
    'displayName' => 'New display name'

$updatedUser = $auth->updateUser($uid, $properties);

$request = \Kreait\Auth\Request\UpdateUser::new()
    ->withDisplayName('New display name');

$updatedUser = $auth->updateUser($uid, $request);

In addition to the properties of a create request, the following properties can be provided:

Property Type Description
deletePhotoUrl boolean Whether or not to delete the user’s photo.
deleteDisplayName boolean Whether or not to delete the user’s display name.
deletePhoneNumber boolean Whether or not to delete the user’s phone number.
deleteProvider string|array One or more identity providers to delete.
customAttributes array A list of custom attributes which will be available in a User’s ID token.

Change a user’s password

$uid = 'some-uid';

$updatedUser = $auth->changeUserPassword($uid, 'new password');

Change a user’s email

$uid = 'some-uid';

$updatedUser = $auth->changeUserEmail($uid, 'user@domain.tld');

Disable a user

$uid = 'some-uid';

$updatedUser = $auth->disableUser($uid);

Enable a user

$uid = 'some-uid';

$updatedUser = $auth->enableUser($uid);

Update custom attributes

$uid = 'some-uid';
$customAttributes = [
    'admin' => true,
    'groupId' => '1234'

$updatedUser = $auth->setCustomUserAttributes($uid, $customAttributes);
$userWithDeletedCustomAttributes = $auth->deleteCustomUserAttributes($uid);


Learn more about custom attributes/claims in the official documentation: Control Access with Custom Claims and Security Rules

Delete a user

$uid = 'some-uid';


Verify a password


This method has the side effect of changing the last login timestamp of the given user. The recommended way to authenticate users in a client/server environment is to use a Firebase Client SDK to authenticate the user and to send an ID Token generated by the client back to the server.

try {
    $user = $auth->verifyPassword($email, $password);
} catch (Kreait\Firebase\Exception\Auth\InvalidPassword $e) {
    echo $e->getMessage();

Using Email Action Codes

Available since v4.37

The Firebase Admin SDK provides the ability to send users emails containing links they can use for password resets, email address verification, and email-based sign-in. These emails are sent by Google and have limited customizability.

If you want to instead use your own email templates and your own email delivery service, you can use the Firebase Admin SDK to programmatically generate the action links for the above flows, which you can include in emails to your users.

Action Code Settings


Action Code Settings are optional.

Action Code Settings allow you to pass additional state via a continue URL which is accessible after the user clicks the email link. This also provides the user the ability to go back to the app after the action is completed. In addition, you can specify whether to handle the email action link directly from a mobile application when it is installed or from a browser.

For links that are meant to be opened via a mobile app, you’ll need to enable Firebase Dynamic Links and perform some tasks to detect these links from your mobile app. Refer to the instructions on how to configure Firebase Dynamic Links for email actions.

Parameter Type Description
continueUrl string|null Sets the continue URL
url string|null Alias for continueUrl
handleCodeInApp bool|null
Whether the email action link will be opened in a mobile app or a web link first.
The default is false. When set to true, the action code link will be be sent
as a Universal Link or Android App Link and will be opened by the app if
installed. In the false case, the code will be sent to the web widget first
and then on continue will redirect to the app if installed.
androidPackageName string|null
Sets the Android package name. This will try to open the link in an android app
if it is installed.
androidInstallApp bool|null
Whether to install the Android app if the device supports it and the app is not
already installed. If this field is provided without a androidPackageName,
an error is thrown explaining that the packageName must be provided in
conjunction with this field.
androidMinimumVersion string|null
If specified, and an older version of the app is installed,
the user is taken to the Play Store to upgrade the app.
The Android app needs to be registered in the Console.
iOSBundleId string|null
Sets the iOS bundle ID. This will try to open the link in an iOS app if it is
installed. The iOS app needs to be registered in the Console.


$actionCodeSettings = [
    'continueUrl' => '',
    'handleCodeInApp' => true,
    'dynamicLinkDomain' => '',
    'androidPackageName' => '',
    'androidMinimumVersion' => '12',
    'androidInstallApp' => true,
    'iOSBundleId' => 'com.example.ios',

Email verification

To generate an email verification link, provide the existing user’s unverified email and optional Action Code Settings. The email used must belong to an existing user. Depending on the method you use, an email will be sent to the user, or you will get an email action link that you can use in a custom email.

$link = $auth->getEmailVerificationLink($email);
$link = $auth->getEmailVerificationLink($email, $actionCodeSettings);

$auth->sendEmailVerificationLink($email, $actionCodeSettings);
$auth->sendEmailVerificationLink($email, null, $locale);
$auth->sendEmailVerificationLink($email, $actionCodeSettings, $locale);

Password reset

To generate a password reset link, provide the existing user’s email and optional Action Code Settings. The email used must belong to an existing user. Depending on the method you use, an email will be sent to the user, or you will get an email action link that you can use in a custom email.

$link = $auth->getPasswordResetLink($email);
$link = $auth->getPasswordResetLink($email, $actionCodeSettings);

$auth->sendPasswordResetLink($email, $actionCodeSettings);
$auth->sendPasswordResetLink($email, null, $locale);
$auth->sendPasswordResetLink($email, $actionCodeSettings, $locale);

Confirm a password reset


Out of the box, Firebase handles the confirmation of password reset requests. You can use your own server to handle account management emails by following the instructions on Customize account management emails and SMS messages

$oobCode = '...'; // Extract the OOB code from the request url (not scope of the SDK (yet :)))
$newPassword = '...';
$invalidatePreviousSessions = true; // default, will revoke current user refresh tokens

try {
    $auth->confirmPasswordReset($oobCode, $newPassword, $invalidatePreviousSessions);
} catch (\Kreait\Firebase\Exception\Auth\ExpiredOobCode $e) {
    // Handle the case of an expired reset code
} catch (\Kreait\Firebase\Exception\Auth\InvalidOobCode $e) {
    // Handle the case of an invalid reset code
} catch (\Kreait\Firebase\Exception\AuthException $e) {
    // Another error has occurred

Invalidate user sessions [1]

This will revoke all sessions for a specified user and disable any new ID tokens for existing sessions from getting minted. Existing ID tokens may remain active until their natural expiration (one hour). To verify that ID tokens are revoked, use Auth::verifyIdToken() with the second parameter set to true.

If the check fails, a RevokedIdToken exception will be thrown.

use Kreait\Firebase\Exception\Auth\RevokedIdToken;

$auth = $factory->createAuth();

$idTokenString = '...';

$verifiedIdToken = $auth->verifyIdToken($idTokenString);

$uid = $verifiedIdToken->getClaim('sub');


try {
    $verifiedIdToken = $auth->verifyIdToken($idTokenString, true);
} catch (RevokedIdToken $e) {
    echo $e->getMessage();


Because Firebase ID tokens are stateless JWTs, you can determine a token has been revoked only by requesting the token’s status from the Firebase Authentication backend. For this reason, performing this check on your server is an expensive operation, requiring an extra network round trip. You can avoid making this network request by setting up Firebase Rules that check for revocation rather than using the Admin SDK to make the check.

For more information, please visit Google: Detect ID token revocation in Database Rules


[1]Google: Revoke refresh tokens