Customize the Firebase Phone Number Verification flow on Android

TheGet started withFirebase Phone Number Verification page details how to integratewithFirebase PNV using thegetVerifiedPhoneNumber() method, which handlesthe entireFirebase PNV flow, from obtaining user consent to making thenecessary network calls to theFirebase PNV backend.

The single-method API (getVerifiedPhoneNumber()) is recommended for mostdevelopers. However, if you need finer-grained control over the interaction withAndroid Credential Manager–for example, to request other credentials along withthe phone number–theFirebase PNV library also provides the following two methods, each of which handlesa different interaction with theFirebase PNV backend:

  • getDigitalCredentialPayload() gets a server-signed request that you willuse to invoke Credential Manager.
  • exchangeCredentialResponseForPhoneNumber() exchanges the response fromCredential Manager for a signed token containing the verified phone number.Billing will occur at this step.

Between calling each of those methods, you are responsible for handling theinteraction with Android's Credential Manager APIs. This page gives an overviewof how you implement this three-part flow.

Before you begin

Set up your Firebase project and import theFirebase PNV dependencies as describedon theGet started page.

1. Get the Digital Credential request payload

Call thegetDigitalCredentialPayload() method to generate a request for thedevice's phone number. In the next step, this request will be the payload ofyour interaction with the Credential Manager API.

// This instance does not require an Activity context.valfpnv=FirebasePhoneNumberVerification.getInstance()// Your request should include a nonce, which will propagate through the flow// and be present in the final response from FPNV. See the section "Verifying// theFirebase PNV token" for details on generating and verifying this.valnonce=fetchNonceFromYourServer()fpnv.getDigitalCredentialPayload(nonce,"https://example.com/privacy-policy").addOnSuccessListener{fpnvDigitalCredentialPayload->// Use the payload in the next step.// ...}.addOnFailureListener{e->/* Handle payload fetch failure */}

2. Make a digital credential request using the Credential Manager

Next, pass the request to the Credential Manager.

To do so, you need to wrap the request payload in a DigitalCredential APIrequest. This request must include the same nonce you passed togetDigitalCredentialPayload().

// This example uses string interpolation for clarity, but you should use some kind of type-safe// serialization method.funbuildDigitalCredentialRequestJson(nonce:String,fpnvDigitalCredentialPayload:String)="""    {      "requests": [        {          "protocol": "openid4vp-v1-unsigned",          "data": {            "response_type": "vp_token",            "response_mode": "dc_api",            "nonce": "$nonce",            "dcql_query": { "credentials": [$fpnvDigitalCredentialPayload] }          }        }      ]    }""".trimIndent()

Having done so, you can make the request using the Credential Manager API:

suspendfunmakeFpnvRequest(context:Activity,nonce:String,fpnvDigitalCredentialPayload:String):GetCredentialResponse{// Helper function to build the digital credential request (defined above).// Pass the same nonce you passed to getDigitalCredentialPayload().valdigitalCredentialRequestJson=buildDigitalCredentialRequestJson(nonce,fpnvDigitalCredentialPayload)// CredentialManager requires an Activity context.valcredentialManager=CredentialManager.create(context)// Build a Credential Manager request that includes the Firebase PNV option. Note that// you can't combine the digital credential option with other options.valrequest=GetCredentialRequest.Builder().addCredentialOption(GetDigitalCredentialOption(digitalCredentialRequestJson)).build()// getCredential is a suspend function, so it must run in a coroutine scope,valcmResponse:GetCredentialResponse=try{credentialManager.getCredential(context,request)}catch(e:GetCredentialException){// If the user cancels the operation, the feature isn't available, or the// SIM doesn't support the feature, a GetCredentialCancellationException// will be returned. Otherwise, a GetCredentialUnsupportedException will// be returned with details in the exception message.throwe}returncmResponse}

If the Credential Manager call succeeds, its response will contain a digitalcredential, which you can extract using code like the following example:

valdcApiResponse=extractApiResponse(cmResponse)
funextractApiResponse(response:GetCredentialResponse):String{valcredential=response.credentialwhen(credential){isDigitalCredential->{valjson=JSONObject(credential.credentialJson)valfirebaseJwtArray=json.getJSONObject("data").getJSONObject("vp_token").getJSONArray("firebase")returnfirebaseJwtArray.getString(0)}else->{// Handle any unrecognized credential type here.Log.e(TAG,"Unexpected type of credential${credential.type}")}}}

3. Exchange the digital credential response for aFirebase PNV token

Finally, call theexchangeCredentialResponseForPhoneNumber() method toexchange the digital credential response for the verified phone number and anFirebase PNV token:

fpnv.exchangeCredentialResponseForPhoneNumber(dcApiResponse).addOnSuccessListener{result->valphoneNumber=result.getPhoneNumber()// Verification successful}.addOnFailureListener{e->/* Handle exchange failure */}

This step will trigger billing when it successfully completes and the verifiedphone number is returned to your app.

4. Verifying theFirebase PNV token

If the flow succeeds, thegetVerifiedPhoneNumber() method returns the verifiedphone number and a signed token containing it. You can use this data in your appas documented by your privacy policy.

If you use the verified phone number outside the app client, you should passaround the token instead of the phone number itself so you can verify itsintegrity when you use it. To verify tokens, you need to implement twoendpoints:

  • A nonce generation endpoint
  • A token verification endpoint

The implementation of these endpoints is up to you; the following examples showhow you might implement them using Node.js and Express.

Generating nonces

This endpoint is responsible for generating and temporarily storing single-usevalues called nonces, which are used to prevent replay attacks against yourendpoints. As an example, you might have an Express route defined like this:

app.get('/fpnvNonce',async(req,res)=>{constnonce=crypto.randomUUID();// TODO: Save the nonce to a database, key store, etc.// You should also assign the nonce an expiration time and periodically// clear expired nonces from your database.awaitpersistNonce({nonce,expiresAt:Date.now()+180000,// Give it a short duration.});// Return the nonce to the caller.res.send({nonce});});

This is the endpoint that the placeholder function,fetchNonceFromYourServer(), in Step 1 would call. The nonce will propagatethrough the various network calls that the client performs and eventually makeits way back to your server in theFirebase PNV token. In the next step, you verifythat the token contains a nonce that you generated.

Verifying tokens

This endpoint receivesFirebase PNV tokens from your client and verifies theirauthenticity. To verify a token, you need to check:

  • Thetyp header is set toJWT.

  • The token is signed using one of the keys published at theFirebase PNV JWKSendpoint withES256 algorithm:

    https://fpnv.googleapis.com/v1beta/jwks
  • The issuer claims contains your Firebase project number and is inthe following format:

    https://fpnv.googleapis.com/projects/FIREBASE_PROJECT_NUMBER

    You can find your Firebase project number on theProject settingspage of the Firebase console.

  • The audience claim is a list that contains your Firebase project number andproject ID and is in the following format:

    [  https://fpnv.googleapis.com/projects/FIREBASE_PROJECT_NUMBER,  https://fpnv.googleapis.com/projects/FIREBASE_PROJECT_ID,]
  • The token has not expired.

  • The token contains a valid nonce. A nonce is valid if:

    • You generated it (that is, it can be found in whatever persistencemechanism you're using)
    • It hasn't already been used
    • It hasn't expired

For example, the Express implementation might look something like the following:

import{JwtVerifier}from"aws-jwt-verify";// Find your Firebase project number in the Firebase console.constFIREBASE_PROJECT_NUMBER="123456789";// The issuer and audience claims of the FPNV token are specific to your// project.constissuer=`https://fpnv.googleapis.com/projects/${FIREBASE_PROJECT_NUMBER}`;constaudience=`https://fpnv.googleapis.com/projects/${FIREBASE_PROJECT_NUMBER}`;// The JWKS URL contains the current public signing keys for FPNV tokens.constjwksUri="https://fpnv.googleapis.com/v1beta/jwks";// Configure a JWT verifier to check the following:// - The token is signed by Google// - The issuer and audience claims match your project// - The token has not yet expired (default begavior)constfpnvVerifier=JwtVerifier.create({issuer,audience,jwksUri});app.post('/verifiedPhoneNumber',async(req,res)=>{if(!req.body)returnres.sendStatus(400);// Get the token from the body of the request.constfpnvToken=req.body;try{// Attempt to verify the token using the verifier configured above.constverifiedPayload=awaitfpnvVerifier.verify(fpnvToken);// Now that you've verified the signature and claims, verify the nonce.// TODO: Try to look up the nonce in your database and remove it if it's// found; if it's not found or it's expired, throw an error.awaittestAndRemoveNonce(verifiedPayload.nonce);// Only after verifying the JWT signature, claims, and nonce, get the// verified phone number from the subject claim.// You can use this value however it's needed by your app.constverifiedPhoneNumber=verifiedPayload.sub;// (Do something with it...)returnres.sendStatus(200);}catch{// If verification fails, reject the token.returnres.sendStatus(400);}});

Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2025-12-11 UTC.