Skip to main content
Whether you are implementing app verification for push, QR code, or in-app flows, you’ll need to consider when to enroll and un-enroll users in your mobile app. This guide will cover the appropriate points in your app’s authentication lifecycle to enroll and un-enroll users by adding and removing device credentials. The code examples below use the push namespace. If you’re implementing QR code or in-app verification, replace push with qr or inapp.

​
When to enroll

App verification enrollment for users is typically an invisible process which happens automatically when they’re signed in to your mobile app. Your app uses one of our Mobile SDKs to generate a cryptographic device credential and bind it to an authenticated user. The recommended place to enroll users by adding a device credential is within a post-authentication handler. This handler should be triggered in the following two scenarios.
  1. Immediately after the user signs in to the app.
  2. When the app is launched and the user is already authenticated (e.g. due to a persistent session).
If your app uses long-lived sessions and doesn’t require frequent sign-ins, the second scenario is especially important. It will ensure that users who launch the app after installing your updated version are enrolled for app verification without explicitly having to sign in again. The following code should be run in both of the above scenarios to enroll a new credential if none exists on the device. 
func enrollCredential() async {
    let response = await authsignal.push.getCredential()

    if response.data != nil {
        // A credential already exists
        return
    }

    // Fetch an enrollment token from your backend
    let token = try await getEnrollmentToken()

    // Silently enroll a new device credential with attestation
    await authsignal.push.addCredential(token: token, performAttestation: true)
}
This code should be run after a user signs in. 
func postSignInHandler() async {
    await enrollCredential()
}
It should also be run when the user launches the app while already authenticated. 
func postLaunchHandler() async {
    if isAuthenticated {
        await enrollCredential()
    }
}
Your backend code to generate the enrollment token should be implemented within an authenticated endpoint. 
// A mock example of an endpoint for generating enrollment tokens
app.post("/generate-enrollment-token", async (req, res) => {
  // Determine user from authenticated request context
  const userId = req.user.sub;

  const { token } = await authsignal.track({
    userId,
    action: "addCredential",
    attributes: {
      scope: "add:authenticators",
    },
  });

  res.json({ token });
});
The add:authenticators scope is required here since we are enrolling a new authentication method in an authenticated context. The action can be any value which describes the enrollment activity and will be used for observability in the Authsignal Portal.

​
Handling app updates

A common question is how to enroll users who are already signed in and just received an app update that introduces app verification. The post-launch handler shown above covers this scenario automatically. No separate flow is required. When an existing authenticated user opens the updated app for the first time:
  1. The post-launch handler runs because the user’s session is still valid.
  2. getCredential returns no credential (since the device hasn’t been enrolled yet on this version).
  3. A new device credential is silently enrolled via addCredential.
For users who already had a credential from a prior version, getCredential short-circuits and no re-enrollment occurs, so the flow is safe to run on every launch.

​
When to un-enroll

The recommended point in your app to un-enroll users for app verification is after sign-out. This means that once signed out users will no longer be enrolled for app verification on that device. 
func postSignOutHandler() async {
    await authsignal.push.removeCredential()
}