Auth Bypass Deep Links

Auth bypass deep links let Revyl start a test from a signed-in app state without automating every login screen. The easiest implementation is:

Add a test-only deep link handler in your app.
Gate that handler with Revyl launch variables.
Open one deep link from revyl device navigate or a YAML navigate step.

Only enable this in simulator, staging, debug, or explicit test builds. Do not ship a permanent auth bypass in production.

Fastest Path For Expo Cloud Agents

Use this path when you already run an Expo development client through revyl dev.

npx expo start --tunnel --dev-client

revyl dev --no-build --tunnel "<expo-dev-client-link>" \
  --launch-var REVYL_AUTH_BYPASS_ENABLED \
  --launch-var REVYL_AUTH_BYPASS_TOKEN

revyl device navigate \
  --url "myapp://revyl-auth?token=$REVYL_AUTH_BYPASS_TOKEN&role=buyer&redirect=%2Fcheckout"

Load the Expo dev client project first, then send the app-specific auth deep link. In managed Expo apps, JavaScript may not automatically see native launch values; use a small native config bridge, verify the token with a staging backend, or use a local demo fallback for sample apps only.

Copy This Contract

Use one route shape across every framework:

myapp://revyl-auth?token=<token>&role=<role>&redirect=<allowlisted-route>

Create these launch variables:

revyl global launch-var create REVYL_AUTH_BYPASS_ENABLED=true
revyl global launch-var create REVYL_AUTH_BYPASS_TOKEN=revyl-demo-token

Then start a device with the variables attached and open the bypass link:

revyl device start \
  --platform ios \
  --launch-var REVYL_AUTH_BYPASS_ENABLED \
  --launch-var REVYL_AUTH_BYPASS_TOKEN

revyl device navigate \
  --url "myapp://revyl-auth?token=revyl-demo-token&role=buyer&redirect=%2Fcheckout"

Use the same URL in YAML tests:

test:
  metadata:
    name: "Auth bypass to checkout"
    platform: ios

  build:
    name: "Shopping App"

  env_vars:
    - REVYL_AUTH_BYPASS_ENABLED
    - REVYL_AUTH_BYPASS_TOKEN

  variables:
    auth_bypass_token: revyl-demo-token

  blocks:
    - type: manual
      step_type: navigate
      step_description: "myapp://revyl-auth?token={{auth_bypass_token}}&role=buyer&redirect=%2Fcheckout"

    - type: validation
      step_description: "The checkout screen is visible and the user is signed in"

App Checklist

Your app owns four small pieces:

Read REVYL_AUTH_BYPASS_ENABLED and REVYL_AUTH_BYPASS_TOKEN at app launch.
Register a handler for myapp://revyl-auth.
Verify the token, role, and redirect before changing app state.
Create a test-only session and route only to an allowlisted destination.

Invalid links should fail visibly in test builds. Show a debug banner, account-screen status, toast, or log line that says why the link was rejected.

Framework Recipes

Pick the recipe closest to your app. The session creation and route names are app-specific, but the Revyl contract stays the same.

Expo / Expo Router

Put the handler near your root layout so it catches initial links and links opened while the app is running.

import { useEffect } from "react";
import * as Linking from "expo-linking";
import { router } from "expo-router";

const allowedRedirects = new Map([
  ["/account", "/(tabs)/account"],
  ["/cart", "/cart"],
  ["/checkout", "/checkout"],
]);
const allowedRoles = new Set(["buyer", "support"]);

function launchValue(key: string) {
  return process.env[key];
}

function handleRevylAuthBypass(rawURL: string) {
  const url = new URL(rawURL);
  if (url.protocol !== "myapp:" || url.hostname !== "revyl-auth") return;

  const enabled = launchValue("REVYL_AUTH_BYPASS_ENABLED") === "true";
  const expectedToken = launchValue("REVYL_AUTH_BYPASS_TOKEN");
  const token = url.searchParams.get("token");
  const role = url.searchParams.get("role") || "buyer";
  const redirect = url.searchParams.get("redirect") || "/account";
  const route = allowedRedirects.get(redirect);

  if (!enabled) throw new Error("Revyl auth bypass is disabled");
  if (!expectedToken || token !== expectedToken) throw new Error("Bad Revyl auth bypass token");
  if (!allowedRoles.has(role)) throw new Error("Role is not allowlisted");
  if (!route) throw new Error("Redirect is not allowlisted");

  createTestSession({ role });
  router.replace(route);
}

export function useRevylAuthBypass() {
  useEffect(() => {
    Linking.getInitialURL().then(url => {
      if (url) handleRevylAuthBypass(url);
    });

    const subscription = Linking.addEventListener("url", event => {
      handleRevylAuthBypass(event.url);
    });

    return () => subscription.remove();
  }, []);
}

In managed Expo apps, JavaScript may not receive native launch values automatically. Use a small native config bridge, verify the token with a staging backend, or follow the Bug Bazaar sample’s demo fallback for a local fixture only.For Expo Router apps, add a route backstop such as app/revyl-auth.tsx that calls the same handler from route params. Expo Router may treat myapp://revyl-auth?... as a normal app route while the development client is already running; the route backstop keeps rejected links visible instead of landing on an unmatched-route screen.

React Native CLI

Use React Native Linking for the deep link and read launch config from your native layer or staging backend.

import { useEffect } from "react";
import { Linking, NativeModules } from "react-native";

const allowedRedirects = new Set(["/account", "/checkout", "/cart"]);
const allowedRoles = new Set(["buyer", "support"]);

async function getLaunchConfig() {
  return NativeModules.LaunchConfig.getRevylAuthBypassConfig();
  // { enabled: boolean, token: string }
}

async function handleRevylAuthBypass(rawURL: string) {
  const url = new URL(rawURL);
  if (url.protocol !== "myapp:" || url.hostname !== "revyl-auth") return;

  const config = await getLaunchConfig();
  const token = url.searchParams.get("token");
  const role = url.searchParams.get("role") || "buyer";
  const redirect = url.searchParams.get("redirect") || "/account";

  if (!config.enabled) throw new Error("Revyl auth bypass is disabled");
  if (token !== config.token) throw new Error("Bad Revyl auth bypass token");
  if (!allowedRoles.has(role)) throw new Error("Role is not allowlisted");
  if (!allowedRedirects.has(redirect)) throw new Error("Redirect is not allowlisted");

  await createTestSession({ role });
  navigationRef.navigate(routeNameForRedirect(redirect));
}

export function useRevylAuthBypass() {
  useEffect(() => {
    Linking.getInitialURL().then(url => {
      if (url) void handleRevylAuthBypass(url);
    });

    const subscription = Linking.addEventListener("url", event => {
      void handleRevylAuthBypass(event.url);
    });

    return () => subscription.remove();
  }, []);
}

For iOS, expose Revyl launch variables from ProcessInfo.processInfo.arguments. For Android, expose them from the launch Intent extras.

Native iOS

Revyl injects launch variables into iOS simulator apps as launch arguments: -REVYL_AUTH_BYPASS_ENABLED true -REVYL_AUTH_BYPASS_TOKEN <token>.

import SwiftUI

private let allowedRedirects: [String: AppRoute] = [
    "/account": .account,
    "/checkout": .checkout,
    "/cart": .cart
]
private let allowedRoles: Set<String> = ["buyer", "support"]

func launchValue(_ key: String) -> String? {
    let args = ProcessInfo.processInfo.arguments
    guard let index = args.firstIndex(of: "-\(key)") else { return nil }
    let valueIndex = args.index(after: index)
    return args.indices.contains(valueIndex) ? args[valueIndex] : nil
}

func queryValue(_ name: String, in url: URL) -> String? {
    let items = URLComponents(url: url, resolvingAgainstBaseURL: false)?.queryItems ?? []
    return items.first(where: { $0.name == name })?.value
}

func handleRevylAuthBypass(_ url: URL) throws {
    guard url.scheme == "myapp", url.host == "revyl-auth" else { return }

    guard launchValue("REVYL_AUTH_BYPASS_ENABLED") == "true" else { throw AuthBypassError.disabled }
    guard queryValue("token", in: url) == launchValue("REVYL_AUTH_BYPASS_TOKEN") else { throw AuthBypassError.badToken }

    let role = queryValue("role", in: url) ?? "buyer"
    let redirect = queryValue("redirect", in: url) ?? "/account"
    guard allowedRoles.contains(role) else { throw AuthBypassError.badRole }
    guard let route = allowedRedirects[redirect] else { throw AuthBypassError.badRedirect }

    TestSession.signIn(role: role)
    AppRouter.shared.navigate(to: route)
}

Call handleRevylAuthBypass(_:) from your SwiftUI .onOpenURL handler or your app delegate URL handler.

Native Android

Revyl injects launch variables into Android as string extras on the app launch intent.

private val allowedRedirects = mapOf(
  "/account" to AppRoute.Account,
  "/checkout" to AppRoute.Checkout,
  "/cart" to AppRoute.Cart,
)
private val allowedRoles = setOf("buyer", "support")

data class RevylAuthConfig(val enabled: Boolean, val token: String?)

fun revylAuthConfig(intent: Intent): RevylAuthConfig {
  return RevylAuthConfig(
    enabled = intent.getStringExtra("REVYL_AUTH_BYPASS_ENABLED") == "true",
    token = intent.getStringExtra("REVYL_AUTH_BYPASS_TOKEN"),
  )
}

fun handleRevylAuthBypass(intent: Intent, config: RevylAuthConfig) {
  val uri = intent.data ?: return
  if (uri.scheme != "myapp" || uri.host != "revyl-auth") return

  val role = uri.getQueryParameter("role") ?: "buyer"
  val redirect = uri.getQueryParameter("redirect") ?: "/account"

  check(config.enabled) { "Revyl auth bypass is disabled" }
  check(uri.getQueryParameter("token") == config.token) { "Bad Revyl auth bypass token" }
  check(role in allowedRoles) { "Role is not allowlisted" }

  val route = allowedRedirects[redirect] ?: error("Redirect is not allowlisted")
  TestSession.signIn(role)
  appRouter.navigate(route)
}

Store revylAuthConfig(launchIntent) when the app starts, then call handleRevylAuthBypass(intent, config) from onCreate and onNewIntent.

Flutter

Flutter apps usually handle the link in Dart and read launch config through a platform channel or staging backend.

import 'package:app_links/app_links.dart';
import 'package:flutter/services.dart';

const launchConfig = MethodChannel('app.launchConfig');
final allowedRedirects = {
  '/account': AppRoute.account,
  '/checkout': AppRoute.checkout,
  '/cart': AppRoute.cart,
};
final allowedRoles = {'buyer', 'support'};

Future<void> handleRevylAuthBypass(Uri uri) async {
  if (uri.scheme != 'myapp' || uri.host != 'revyl-auth') return;

  final config = await launchConfig.invokeMapMethod<String, String>('revylAuthBypass');
  final enabled = config?['REVYL_AUTH_BYPASS_ENABLED'] == 'true';
  final expectedToken = config?['REVYL_AUTH_BYPASS_TOKEN'];
  final role = uri.queryParameters['role'] ?? 'buyer';
  final redirect = uri.queryParameters['redirect'] ?? '/account';

  if (!enabled) throw StateError('Revyl auth bypass is disabled');
  if (uri.queryParameters['token'] != expectedToken) throw StateError('Bad Revyl auth bypass token');
  if (!allowedRoles.contains(role)) throw StateError('Role is not allowlisted');

  final route = allowedRedirects[redirect];
  if (route == null) throw StateError('Redirect is not allowlisted');

  await TestSession.signIn(role: role);
  appRouter.go(route);
}

Future<void> installRevylAuthBypass() async {
  final links = AppLinks();
  final initial = await links.getInitialLink();
  if (initial != null) await handleRevylAuthBypass(initial);
  links.uriLinkStream.listen(handleRevylAuthBypass);
}

Implement the platform channel with the native iOS and Android launch-config snippets above, or verify the token against your staging backend from Dart.

What To Verify

Before relying on the bypass in a test, confirm each case is visible:

Valid token, role, and redirect signs in and routes to the target screen.
Wrong token is rejected.
Missing or disabled REVYL_AUTH_BYPASS_ENABLED is rejected.
Unknown role is rejected.
Unknown redirect is rejected.
The handler is unavailable in production builds.

Bug Bazaar Sample

This repo includes the runnable Expo sample in internal-apps/bug-bazaar:

revyl device navigate \
  --url "bug-bazaar://revyl-auth?token=revyl-demo-token&role=collector&redirect=%2Fcheckout"

The Account tab shows whether the auth bypass link is idle, accepted, or rejected. Bug Bazaar is a managed Expo sample, so it uses a demo fallback token when no native launch-config bridge is present. Customer apps should wire REVYL_AUTH_BYPASS_TOKEN into native launch config or verify the token with a staging backend.

Getting Started

Guides

CLI

Builds

Tests

Develop

Atlas

Integrations

Appendix

Fastest Path For Expo Cloud Agents

Copy This Contract

App Checklist

Framework Recipes

What To Verify

Bug Bazaar Sample

​Fastest Path For Expo Cloud Agents

​Copy This Contract

​App Checklist

​Framework Recipes

​What To Verify

​Bug Bazaar Sample

Fastest Path For Expo Cloud Agents

Copy This Contract

App Checklist

Framework Recipes

What To Verify

Bug Bazaar Sample