Getting Started

Install

You can use our AI-Assisted Setup to install the plugin. Add the Capgo skills to your AI tool using the following command:

npx skills add https://github.com/Cap-go/capgo-skills --skill capacitor-plugins

Then use the following prompt:

Use the `capacitor-plugins` skill from `Cap-go/capgo-skills` to install the `@capgo/capacitor-firebase-authentication` plugin in my project.

If you prefer Manual Setup, install the plugin by running the following commands and follow the platform-specific instructions below:

bun add @capgo/capacitor-firebase-authentication
bunx cap sync

Import

import { FirebaseAuthentication } from '@capgo/capacitor-firebase-authentication';

API Overview

applyActionCode

Applies a verification code sent to the user by email.

import { FirebaseAuthentication } from '@capgo/capacitor-firebase-authentication';

await FirebaseAuthentication.applyActionCode({ oobCode: 'oob-code' });

confirmPasswordReset

Completes the password reset process.

import { FirebaseAuthentication } from '@capgo/capacitor-firebase-authentication';

await FirebaseAuthentication.confirmPasswordReset({
  oobCode: 'oob-code',
  newPassword: 'new-password',
});

confirmVerificationCode

Finishes the phone number verification process.

import { FirebaseAuthentication } from '@capgo/capacitor-firebase-authentication';

const result = await FirebaseAuthentication.confirmVerificationCode({
  verificationId: 'phoneCodeSent',
  verificationCode: 'phoneCodeSent',
});
// The result holds sensitive values: use it without logging it.

createUserWithEmailAndPassword

Creates a new user account with email and password. If the new account was created, the user is signed in automatically.

import { FirebaseAuthentication } from '@capgo/capacitor-firebase-authentication';

const result = await FirebaseAuthentication.createUserWithEmailAndPassword({
  email: 'user@example.com',
  password: 'password',
});
// The result holds sensitive values: use it without logging it.

deleteUser

Deletes and signs out the user.

import { FirebaseAuthentication } from '@capgo/capacitor-firebase-authentication';

await FirebaseAuthentication.deleteUser();

fetchSignInMethodsForEmail

Fetches the sign-in methods for an email address.

import { FirebaseAuthentication } from '@capgo/capacitor-firebase-authentication';

const result = await FirebaseAuthentication.fetchSignInMethodsForEmail({ email: 'user@example.com' });
console.log(result);

getCurrentUser

Fetches the currently signed-in user.

import { FirebaseAuthentication } from '@capgo/capacitor-firebase-authentication';

const result = await FirebaseAuthentication.getCurrentUser();
// The result holds sensitive values: use it without logging it.

getPendingAuthResult

Returns the SignInResult if your app launched a web sign-in flow and the OS cleans up the app while in the background.

Only available for Android.

import { FirebaseAuthentication } from '@capgo/capacitor-firebase-authentication';

const result = await FirebaseAuthentication.getPendingAuthResult();
// The result holds sensitive values: use it without logging it.

getIdToken

Fetches the Firebase Auth ID Token for the currently signed-in user.

import { FirebaseAuthentication } from '@capgo/capacitor-firebase-authentication';

const result = await FirebaseAuthentication.getIdToken();
// The result holds sensitive values: use it without logging it.

getIdTokenResult

Returns a deserialized JSON Web Token (JWT) used to identify the user to a Firebase service.

import { FirebaseAuthentication } from '@capgo/capacitor-firebase-authentication';

const result = await FirebaseAuthentication.getIdTokenResult();
// The result holds sensitive values: use it without logging it.

getRedirectResult

Returns the SignInResult from the redirect-based sign-in flow.

If sign-in was unsuccessful, fails with an error. If no redirect operation was called, returns a SignInResult with a null user.

Only available for Web.

import { FirebaseAuthentication } from '@capgo/capacitor-firebase-authentication';

const result = await FirebaseAuthentication.getRedirectResult();
// The result holds sensitive values: use it without logging it.

getTenantId

Get the tenant id.

import { FirebaseAuthentication } from '@capgo/capacitor-firebase-authentication';

const result = await FirebaseAuthentication.getTenantId();
console.log(result);

isSignInWithEmailLink

Checks if an incoming link is a sign-in with email link suitable for signInWithEmailLink.

import { FirebaseAuthentication } from '@capgo/capacitor-firebase-authentication';

const result = await FirebaseAuthentication.isSignInWithEmailLink({ emailLink: 'https://example.com' });
// The result holds sensitive values: use it without logging it.

linkWithApple

Links the user account with Apple authentication provider.

The user must be logged in on the native layer. The skipNativeAuth configuration option has no effect here.

import { FirebaseAuthentication } from '@capgo/capacitor-firebase-authentication';

const result = await FirebaseAuthentication.linkWithApple();
// The result holds sensitive values: use it without logging it.

linkWithEmailAndPassword

Links the user account with Email authentication provider.

The user must be logged in on the native layer. The skipNativeAuth configuration option has no effect here.

import { FirebaseAuthentication } from '@capgo/capacitor-firebase-authentication';

const result = await FirebaseAuthentication.linkWithEmailAndPassword({
  email: 'user@example.com',
  password: 'password',
});
// The result holds sensitive values: use it without logging it.

linkWithEmailLink

Links the user account with Email authentication provider.

The user must be logged in on the native layer. The skipNativeAuth configuration option has no effect here.

import { FirebaseAuthentication } from '@capgo/capacitor-firebase-authentication';

const result = await FirebaseAuthentication.linkWithEmailLink({
  email: 'user@example.com',
  emailLink: 'https://example.com',
});
// The result holds sensitive values: use it without logging it.

linkWithFacebook

Links the user account with Facebook authentication provider.

The user must be logged in on the native layer. The skipNativeAuth configuration option has no effect here.

import { FirebaseAuthentication } from '@capgo/capacitor-firebase-authentication';

const result = await FirebaseAuthentication.linkWithFacebook();
// The result holds sensitive values: use it without logging it.

linkWithGameCenter

Links the user account with Game Center authentication provider.

The user must be logged in on the native layer. The skipNativeAuth configuration option has no effect here.

Only available for iOS.

import { FirebaseAuthentication } from '@capgo/capacitor-firebase-authentication';

const result = await FirebaseAuthentication.linkWithGameCenter();
// The result holds sensitive values: use it without logging it.

linkWithGithub

Links the user account with GitHub authentication provider.

The user must be logged in on the native layer. The skipNativeAuth configuration option has no effect here.

import { FirebaseAuthentication } from '@capgo/capacitor-firebase-authentication';

const result = await FirebaseAuthentication.linkWithGithub();
// The result holds sensitive values: use it without logging it.

linkWithGoogle

Links the user account with Google authentication provider.

The user must be logged in on the native layer. The skipNativeAuth configuration option has no effect here.

import { FirebaseAuthentication } from '@capgo/capacitor-firebase-authentication';

const result = await FirebaseAuthentication.linkWithGoogle();
// The result holds sensitive values: use it without logging it.

linkWithMicrosoft

Links the user account with Microsoft authentication provider.

The user must be logged in on the native layer. The skipNativeAuth configuration option has no effect here.

import { FirebaseAuthentication } from '@capgo/capacitor-firebase-authentication';

const result = await FirebaseAuthentication.linkWithMicrosoft();
// The result holds sensitive values: use it without logging it.

linkWithOpenIdConnect

Links the user account with an OpenID Connect provider.

import { FirebaseAuthentication } from '@capgo/capacitor-firebase-authentication';

const result = await FirebaseAuthentication.linkWithOpenIdConnect({ providerId: 'provider-id-123' });
// The result holds sensitive values: use it without logging it.

linkWithPhoneNumber

Links the user account with Phone Number authentication provider.

The user must be logged in on the native layer. The skipNativeAuth configuration option has no effect here.

Use the phoneVerificationCompleted listener to be notified when the verification is completed. Use the phoneVerificationFailed listener to be notified when the verification is failed. Use the phoneCodeSent listener to get the verification id.

import { FirebaseAuthentication } from '@capgo/capacitor-firebase-authentication';

await FirebaseAuthentication.linkWithPhoneNumber({ phoneNumber: "+16505550101" });

linkWithPlayGames

Links the user account with Play Games authentication provider.

The user must be logged in on the native layer. The skipNativeAuth configuration option has no effect here.

Only available for Android.

import { FirebaseAuthentication } from '@capgo/capacitor-firebase-authentication';

const result = await FirebaseAuthentication.linkWithPlayGames();
// The result holds sensitive values: use it without logging it.

linkWithTwitter

Links the user account with Twitter authentication provider.

The user must be logged in on the native layer. The skipNativeAuth configuration option has no effect here.

import { FirebaseAuthentication } from '@capgo/capacitor-firebase-authentication';

const result = await FirebaseAuthentication.linkWithTwitter();
// The result holds sensitive values: use it without logging it.

linkWithYahoo

Links the user account with Yahoo authentication provider.

The user must be logged in on the native layer. The skipNativeAuth configuration option has no effect here.

import { FirebaseAuthentication } from '@capgo/capacitor-firebase-authentication';

const result = await FirebaseAuthentication.linkWithYahoo();
// The result holds sensitive values: use it without logging it.

reload

Reloads user account data, if signed in.

import { FirebaseAuthentication } from '@capgo/capacitor-firebase-authentication';

await FirebaseAuthentication.reload();

revokeAccessToken

Revokes the given access token. Currently only supports Apple OAuth access tokens.

import { FirebaseAuthentication } from '@capgo/capacitor-firebase-authentication';

await FirebaseAuthentication.revokeAccessToken({ token: 'token-123' });

sendEmailVerification

Sends a verification email to the currently signed in user.

import { FirebaseAuthentication } from '@capgo/capacitor-firebase-authentication';

await FirebaseAuthentication.sendEmailVerification();

sendPasswordResetEmail

Sends a password reset email.

import { FirebaseAuthentication } from '@capgo/capacitor-firebase-authentication';

await FirebaseAuthentication.sendPasswordResetEmail({ email: 'user@example.com' });

sendSignInLinkToEmail

Sends a sign-in email link to the user with the specified email.

To complete sign in with the email link, call signInWithEmailLink with the email address and the email link supplied in the email sent to the user.

import { FirebaseAuthentication } from '@capgo/capacitor-firebase-authentication';

await FirebaseAuthentication.sendSignInLinkToEmail({
  email: 'user@example.com',
  actionCodeSettings: { url: 'https://example.com' },
});

setLanguageCode

Sets the user-facing language code for auth operations.

import { FirebaseAuthentication } from '@capgo/capacitor-firebase-authentication';

await FirebaseAuthentication.setLanguageCode({ languageCode: "en-US" });

setPersistence

Sets the type of persistence for the currently saved auth session.

Only available for Web.

import { FirebaseAuthentication, Persistence } from '@capgo/capacitor-firebase-authentication';

await FirebaseAuthentication.setPersistence({ persistence: Persistence.IndexedDbLocal });

setTenantId

Sets the tenant id.

import { FirebaseAuthentication } from '@capgo/capacitor-firebase-authentication';

await FirebaseAuthentication.setTenantId({ tenantId: 'tenant-id-123' });

signInAnonymously

Signs in as an anonymous user.

import { FirebaseAuthentication } from '@capgo/capacitor-firebase-authentication';

const result = await FirebaseAuthentication.signInAnonymously();
// The result holds sensitive values: use it without logging it.

signInWithApple

Starts the Apple sign-in flow.

import { FirebaseAuthentication } from '@capgo/capacitor-firebase-authentication';

const result = await FirebaseAuthentication.signInWithApple();
// The result holds sensitive values: use it without logging it.

signInWithCustomToken

Starts the Custom Token sign-in flow.

This method cannot be used in combination with skipNativeAuth on Android and iOS. In this case you have to use the signInWithCustomToken interface of the Firebase JS SDK directly.

import { FirebaseAuthentication } from '@capgo/capacitor-firebase-authentication';

const result = await FirebaseAuthentication.signInWithCustomToken({ token: 'token-123' });
// The result holds sensitive values: use it without logging it.

signInWithEmailAndPassword

Starts the sign-in flow using an email and password.

import { FirebaseAuthentication } from '@capgo/capacitor-firebase-authentication';

const result = await FirebaseAuthentication.signInWithEmailAndPassword({
  email: 'user@example.com',
  password: 'password',
});
// The result holds sensitive values: use it without logging it.

signInWithEmailLink

Signs in using an email and sign-in email link.

import { FirebaseAuthentication } from '@capgo/capacitor-firebase-authentication';

const result = await FirebaseAuthentication.signInWithEmailLink({
  email: 'user@example.com',
  emailLink: 'https://example.com',
});
// The result holds sensitive values: use it without logging it.

signInWithFacebook

Starts the Facebook sign-in flow.

import { FirebaseAuthentication } from '@capgo/capacitor-firebase-authentication';

const result = await FirebaseAuthentication.signInWithFacebook();
// The result holds sensitive values: use it without logging it.

signInWithGameCenter

Starts the Game Center sign-in flow.

Only available for iOS.

import { FirebaseAuthentication } from '@capgo/capacitor-firebase-authentication';

const result = await FirebaseAuthentication.signInWithGameCenter();
// The result holds sensitive values: use it without logging it.

signInWithGithub

Starts the GitHub sign-in flow.

import { FirebaseAuthentication } from '@capgo/capacitor-firebase-authentication';

const result = await FirebaseAuthentication.signInWithGithub();
// The result holds sensitive values: use it without logging it.

signInWithGoogle

Starts the Google sign-in flow.

import { FirebaseAuthentication } from '@capgo/capacitor-firebase-authentication';

const result = await FirebaseAuthentication.signInWithGoogle();
// The result holds sensitive values: use it without logging it.

signInWithMicrosoft

Starts the Microsoft sign-in flow.

import { FirebaseAuthentication } from '@capgo/capacitor-firebase-authentication';

const result = await FirebaseAuthentication.signInWithMicrosoft();
// The result holds sensitive values: use it without logging it.

signInWithOpenIdConnect

Starts the OpenID Connect sign-in flow.

import { FirebaseAuthentication } from '@capgo/capacitor-firebase-authentication';

const result = await FirebaseAuthentication.signInWithOpenIdConnect({ providerId: 'provider-id-123' });
// The result holds sensitive values: use it without logging it.

signInWithPhoneNumber

Starts the sign-in flow using a phone number.

Use the phoneVerificationCompleted listener to be notified when the verification is completed. Use the phoneVerificationFailed listener to be notified when the verification is failed. Use the phoneCodeSent listener to get the verification id.

Only available for Android and iOS.

import { FirebaseAuthentication } from '@capgo/capacitor-firebase-authentication';

await FirebaseAuthentication.signInWithPhoneNumber({ phoneNumber: "+16505550101" });

signInWithPlayGames

Starts the Play Games sign-in flow.

Only available for Android.

import { FirebaseAuthentication } from '@capgo/capacitor-firebase-authentication';

const result = await FirebaseAuthentication.signInWithPlayGames();
// The result holds sensitive values: use it without logging it.

signInWithTwitter

Starts the Twitter sign-in flow.

import { FirebaseAuthentication } from '@capgo/capacitor-firebase-authentication';

const result = await FirebaseAuthentication.signInWithTwitter();
// The result holds sensitive values: use it without logging it.

signInWithYahoo

Starts the Yahoo sign-in flow.

import { FirebaseAuthentication } from '@capgo/capacitor-firebase-authentication';

const result = await FirebaseAuthentication.signInWithYahoo();
// The result holds sensitive values: use it without logging it.

signOut

Starts the sign-out flow.

import { FirebaseAuthentication } from '@capgo/capacitor-firebase-authentication';

await FirebaseAuthentication.signOut();

unlink

Unlinks a provider from a user account.

import { FirebaseAuthentication, ProviderId } from '@capgo/capacitor-firebase-authentication';

const result = await FirebaseAuthentication.unlink({ providerId: ProviderId.APPLE });
// The result holds sensitive values: use it without logging it.

updateEmail

Updates the email address of the currently signed in user.

import { FirebaseAuthentication } from '@capgo/capacitor-firebase-authentication';

await FirebaseAuthentication.updateEmail({ newEmail: 'user@example.com' });

updatePassword

Updates the password of the currently signed in user.

import { FirebaseAuthentication } from '@capgo/capacitor-firebase-authentication';

await FirebaseAuthentication.updatePassword({ newPassword: 'new-password' });

updateProfile

Updates a user’s profile data.

import { FirebaseAuthentication } from '@capgo/capacitor-firebase-authentication';

await FirebaseAuthentication.updateProfile({
  displayName: 'display',
  photoUrl: 'https://example.com',
});

useAppLanguage

Sets the user-facing language code to be the default app language.

import { FirebaseAuthentication } from '@capgo/capacitor-firebase-authentication';

await FirebaseAuthentication.useAppLanguage();

useEmulator

Instrument your app to talk to the Authentication emulator.

import { FirebaseAuthentication } from '@capgo/capacitor-firebase-authentication';

await FirebaseAuthentication.useEmulator({ host: "127.0.0.1" });

verifyBeforeUpdateEmail

Verifies the new email address before updating the email address of the currently signed in user.

import { FirebaseAuthentication } from '@capgo/capacitor-firebase-authentication';

await FirebaseAuthentication.verifyBeforeUpdateEmail({ newEmail: 'user@example.com' });

checkAppTrackingTransparencyPermission

Checks the current status of app tracking transparency.

Only available on iOS.

import { FirebaseAuthentication } from '@capgo/capacitor-firebase-authentication';

const result = await FirebaseAuthentication.checkAppTrackingTransparencyPermission();
console.log(result);

requestAppTrackingTransparencyPermission

Opens the system dialog to authorize app tracking transparency.

Attention: The user may have disabled the tracking request in the device settings, see Apple’s documentation.

Only available on iOS.

import { FirebaseAuthentication } from '@capgo/capacitor-firebase-authentication';

const result = await FirebaseAuthentication.requestAppTrackingTransparencyPermission();
console.log(result);

Type Reference

ApplyActionCodeOptions

export interface ApplyActionCodeOptions {
  /**
   * A verification code sent to the user.
   *
   * @since 0.2.2
   */
  oobCode: string;
}

ConfirmPasswordResetOptions

export interface ConfirmPasswordResetOptions {
  /**
   * A verification code sent to the user.
   *
   * @since 0.2.2
   */
  oobCode: string;
  /**
   * The new password.
   *
   * @since 0.2.2
   */
  newPassword: string;
}

ConfirmVerificationCodeOptions

export interface ConfirmVerificationCodeOptions {
  /**
   * The verification ID received from the `phoneCodeSent` listener.
   *
   * The `verificationCode` option must also be provided.
   *
   * @since 5.0.0
   */
  verificationId: string;
  /**
   * The verification code either received from the `phoneCodeSent` listener or entered by the user.
   *
   * The `verificationId` option must also be provided.
   *
   * @since 5.0.0
   */
  verificationCode: string;
}

SignInResult

export interface SignInResult {
  /**
   * The currently signed-in user, or null if there isn't any.
   *
   * @since 0.1.0
   */
  user: User | null;
  /**
   * Credentials returned by an auth provider.
   *
   * @since 0.1.0
   */
  credential: AuthCredential | null;
  /**
   * Additional user information from a federated identity provider.
   *
   * @since 0.5.1
   */
  additionalUserInfo: AdditionalUserInfo | null;
}

CreateUserWithEmailAndPasswordOptions

export interface CreateUserWithEmailAndPasswordOptions {
  /**
   * @since 0.2.2
   */
  email: string;
  /**
   * @since 0.2.2
   */
  password: string;
}

FetchSignInMethodsForEmailOptions

export interface FetchSignInMethodsForEmailOptions {
  /**
   * The user's email address.
   *
   * @since 6.0.0
   */
  email: string;
}

FetchSignInMethodsForEmailResult

export interface FetchSignInMethodsForEmailResult {
  /**
   * The sign-in methods for the specified email address.
   *
   * This list is empty when [Email Enumeration Protection](https://cloud.google.com/identity-platform/docs/admin/email-enumeration-protection)
   * is enabled, irrespective of the number of authentication methods available for the given email.
   *
   * @since 6.0.0
   */
  signInMethods: string[];
}

GetCurrentUserResult

export interface GetCurrentUserResult {
  /**
   * The currently signed-in user, or null if there isn't any.
   *
   * @since 0.1.0
   */
  user: User | null;
}

GetIdTokenOptions

export interface GetIdTokenOptions {
  /**
   * Force refresh regardless of token expiration.
   *
   * @since 0.1.0
   */
  forceRefresh: boolean;
}

GetIdTokenResult

export interface GetIdTokenResult {
  /**
   * The Firebase Auth ID token JWT string.
   *
   * @since 0.1.0
   */
  token: string;
}

GetIdTokenResultOptions

export interface GetIdTokenResultOptions {
  /**
   * Force refresh regardless of token expiration.
   *
   * @since 7.4.0
   */
  forceRefresh: boolean;
}

GetIdTokenResultResult

export interface GetIdTokenResultResult {
  /**
   * The authentication time in milliseconds since the epoch.
   *
   * This is the time the user authenticated (signed in) and not the time the token was refreshed.
   *
   * @since 7.4.0
   */
  authTime: number;
  /**
   * The ID token expiration time in milliseconds since the epoch.
   *
   * @since 7.4.0
   */
  expirationTime: number;
  /**
   * The ID token issuance time in milliseconds since the epoch.
   *
   * @since 7.4.0
   */
  issuedAtTime: number;
  /**
   * The sign-in provider through which the ID token was obtained.
   *
   * @since 7.4.0
   */
  signInProvider: string | null;
  /**
   * The type of second factor associated with this session, provided the user was multi-factor
   * authenticated (eg. phone, etc).
   *
   * @since 7.4.0
   */
  signInSecondFactor: string | null;
  /**
   * The entire payload claims of the ID token including the standard reserved claims as well as
   * the custom claims.
   *
   * @since 7.4.0
   */
  claims: Record<string, unknown>;
}

Source Of Truth

This page is generated from the plugin’s src/definitions.ts. Re-run the sync when the public API changes upstream.

Keep going from Getting Started

If you are using Getting Started to plan authentication and account flows, connect it with @capgo/capacitor-social-login for the implementation detail in @capgo/capacitor-social-login, @capgo/capacitor-passkey for the implementation detail in @capgo/capacitor-passkey, @capgo/capacitor-native-biometric for the implementation detail in @capgo/capacitor-native-biometric, Two-factor authentication for the implementation detail in Two-factor authentication, and SSO (Enterprise) for the implementation detail in SSO (Enterprise).