Enrollment lifecycle

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.

Immediately after the user signs in to the app.
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)
}

suspend fun enrollCredential() {
    val response = authsignal.push.getCredential()

    if (response.data != null) {
        // A credential already exists
        return
    }

    // Fetch an enrollment token from your backend
    val token = getEnrollmentToken()

    // Silently enroll a new device credential with attestation
    authsignal.push.addCredential(token = token, performAttestation = true)
}

async function enrollCredential() {
  const response = await authsignal.push.getCredential();

  if (response.data) {
    // A credential already exists
    return;
  }

  // Fetch an enrollment token from your backend by calling track
  const token = await getEnrollmentToken();

  // Silently enroll a new device credential with attestation
  await authsignal.push.addCredential({ token, performAttestation: true });
}

Future<void> enrollCredential() async {
  final response = await authsignal.push.getCredential();

  if (response.data != null) {
    // A credential already exists
    return;
  }

  // Fetch an enrollment token from your backend
  final token = await getEnrollmentToken();

  // Silently enroll a new device credential
  await authsignal.push.addCredential(token);
}

This code should be run after a user signs in.

func postSignInHandler() async {
    await enrollCredential()
}

suspend fun postSignInHandler() {
    enrollCredential()
}

async function postSignInHandler() {
  await enrollCredential();
}

Future<void> 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()
    }
}

suspend fun postLaunchHandler() {
    if (isAuthenticated) {
        enrollCredential()
    }
}

async function postLaunchHandler() {
  if (isAuthenticated) {
    await enrollCredential();
  }
}

Future<void> 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:

The post-launch handler runs because the user’s session is still valid.
getCredential returns no credential (since the device hasn’t been enrolled yet on this version).
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.

Keeping credentials alive

By default a device credential never expires. You can optionally configure a credential lifetime on the push authenticator so that credentials expire if the device goes quiet for too long. This is useful for pruning credentials belonging to devices a user no longer has. Set the lifetime in the Authsignal Portal under the push authenticator configuration. When it’s unset, credentials never expire and no keep-alive is needed. When a lifetime is configured, a credential expires if it isn’t kept alive within that window. An expired credential is removed: it’s excluded from push challenges and getCredential returns no credential. To stay enrolled, the device extends its own lease by calling updateCredential with resetExpiry set to true.

await authsignal.push.updateCredential(resetExpiry: true)

authsignal.push.updateCredential(resetExpiry = true)

await authsignal.push.updateCredential({ resetExpiry: true });

The natural place to make this call is the same post-launch handler you already use to enroll, since it runs whenever an authenticated user opens the app. And because getCredential returns no credential once one expires, the enrollCredential function shown above already handles the expired case: it enrolls a fresh credential when none is found.

Detecting invalid push tokens

When you start a push challenge and your tenant uses the Default or Firebase provider, the response includes deliveryResults: the outcome of the send for each of the user’s targeted devices. An entry with no errorCode succeeded.

{
  "challengeId": "8f2b1c94-5a3e-4d17-9c62-0b7a4e6d1f38",
  "deliveryResults": [
    {"userAuthenticatorId": "4efd2d0d-3278-4e03-8143-d9a0850bebc0"},
    {"userAuthenticatorId": "b1c8e7a2-9f45-4d31-8e07-2a6c5b3d9e14", "errorCode": "Unregistered"}
  ]
}

When a send fails and the provider tells us why, Authsignal also stores errorCode alongside an erroredAt timestamp on the device’s authenticator.

Reading the error state

Get Authenticators returns erroredAt and errorCode, so you can surface the state in your own UI, for example to prompt the user to open your app on that device:

[
  {
    "userAuthenticatorId": "4efd2d0d-3278-4e03-8143-d9a0850bebc0",
    "verificationMethod": "PUSH",
    "deviceName": "iPhone 16 Pro",
    "createdAt": "2024-05-13T04:59:02.640Z",
    "lastVerifiedAt": "2024-07-12T09:11:24.640Z",
    "erroredAt": "2024-07-13T02:43:37.640Z",
    "errorCode": "Unregistered"
  }
]

Codes that mean the device is unreachable

Some codes mean the device will never become reachable again on its current token. These are documented as permanent by the providers, and typically mean your app has been removed from the device:

Code	Provider	Meaning
`Unregistered`	APNs	The token is no longer active
`ExpiredToken`	APNs	The token has expired
`UNREGISTERED`	FCM	The app instance was unregistered

Treat one of these as a good signal that the device is gone for good and that the user should verify another way. See the provider documentation for the full list of codes.

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

suspend fun postSignOutHandler() {
    authsignal.push.removeCredential()
}

function postSignOutHandler() {
  await authsignal.push.removeCredential();
}

Future<void> postSignOutHandler() async {
  await authsignal.push.removeCredential();
}

Getting started

Integrations

Authentication methods

Implementation options

Actions & rules

Users

Advanced usage

Enrollment lifecycle

When to enroll

Handling app updates

Keeping credentials alive

Detecting invalid push tokens

Reading the error state

Codes that mean the device is unreachable

When to un-enroll

​When to enroll

​Handling app updates

​Keeping credentials alive

​Detecting invalid push tokens

​Reading the error state

​Codes that mean the device is unreachable

​When to un-enroll

When to enroll

Handling app updates

Keeping credentials alive

Detecting invalid push tokens

Reading the error state

Codes that mean the device is unreachable

When to un-enroll