Customize the auth gate in Replay

The ReplayGate component wraps the entire Replay UI and controls whether users can reach it. By ejecting and replacing it, you can require users to authenticate before Replay opens. Examples include completing an OAuth 2.0 flow, entering an API key, or signing in with your own identity provider.

When a user authenticates, call setEnvironmentValues to set the token as an environment variable. Replay picks up the value automatically and prefills it in every operation that declares a matching security scheme.

Make sure you have the following:

• a basic understanding of TypeScript and React hooks
• an OpenAPI description file with at least one security scheme defined
• credentials for the identity provider you want to integrate (client ID, authorization endpoint, and so on)

To customize the auth gate, first eject the component:

npx @redocly/cli eject component 'ReplayGate/ReplayGate.tsx'

This command creates a local copy of ReplayGate.tsx in your project's @theme/components/ReplayGate/ folder.

Replay generates one environment per API server defined in your OpenAPI description. The environment name is the server's name, description, or URL — whichever is set first.

Each environment has a set of inputs derived from the operation's security schemes. The input names follow the pattern {schemeId}{suffix}. schemeId is the security scheme identifier from your OpenAPI description, and the suffix depends on the scheme type:

Pass the input name as the key when calling setEnvironmentValues:

setEnvironmentValues(selectedEnvironment, { bearerAuth_token: token });

Replay resolves this value at request time and injects it into the Authorization header automatically.

Create new environments when your gate issues credentials that don't belong to any environment declared in your OpenAPI description. For example, a per-user sandbox obtained at sign-in. Replay creates that environment instead of ignoring the call.

To create a new environment:

1. Call setEnvironmentValues with a name that doesn't match any environment in your OpenAPI description.

2. Creating an environment doesn't select it. Call setSelectedEnvironment to make it active:

   setEnvironmentValues('Authorized', { bearerAuth_token: { value: token, isSecret: true } });
   setSelectedEnvironment('Authorized');
   

The new environment takes its server from the environment selected by the page. Requests reach the same host the page targets. The first server in your OpenAPI description is the fallback.

Only the names your gate passes to setEnvironmentValues create environments. Environment values from the project configuration can't do that, so a name that doesn't match an existing environment is silently dropped.

Environments created this way are exempt from the allowedEnvironments setting, because the gate requested them explicitly. Users can't rename or delete these environments from the environments panel, as your gate recreates them on the next page load.

In projects that set allowedEnvironments, values users type into created environments are not restored on page reload. Your gate re-injects its own values. The credentials it manages are unaffected.

A key passed to setEnvironmentValues does not have to match a name generated from the OpenAPI description. If the key matches an existing input (a security scheme, path parameter, or dynamic value), Replay overwrites that input's value. If it doesn't match anything, Replay creates a new input with that name in the target environment. This behavior is useful for injecting values your OpenAPI description doesn't model as security, such as an internal tracing header.

By default, a value is not masked in the Replay UI. A plain string keeps an existing input's current masking, and a newly created input starts out unmasked. Pass an object instead of a string to control this explicitly:

// Plain string: sets the value, keeps whatever masking the input already had
// (or unmasked, if this creates a new input).
setEnvironmentValues(selectedEnvironment, { bearerAuth_token: token });

// { value, isSecret }: also sets whether Replay masks the value.
setEnvironmentValues(selectedEnvironment, {
  bearerAuth_token: { value: token, isSecret: true },
});

The default ReplayGate passes children through without any auth check — all users can access Replay immediately. If that is acceptable for your use case, you do not need to eject this component.

import React from 'react';
import type { ReplayGateProps } from '@redocly/theme/components/ReplayGate/ReplayGate';

export function ReplayGate({ children }: ReplayGateProps) {
  return <>{children}</>;
}

The following example implements a full OAuth 2.0 authorization code flow using a popup window. It validates any stored token on mount and opens the authorization URL automatically if the token is missing or expired. After a successful sign-in, it injects the token into Replay's active environment.

While that initial check runs, it shows a loading spinner instead of the sign-in button. Without a distinct loading state, returning users with a valid token would see a flash. The sign-in button would show for however long the validation request takes.

The panel is dismissible: a close button and a click on the backdrop call onClose, which closes the Replay overlay. Dismissing never falls through to Replay, so a successful sign-in stays the only way past the gate.

Replace the constants at the top (CLIENT_ID, OAUTH_BASE_URL, REDIRECT_URI, and TOKEN_INPUT_NAME) with values from your own identity provider.

import React, { useCallback, useEffect, useRef, useState } from 'react';
import styled, { keyframes } from 'styled-components';
import { CloseIcon } from '@redocly/theme/icons/CloseIcon/CloseIcon';
import type { ReplayGateProps } from '@redocly/theme/components/ReplayGate/ReplayGate';

// Replace with your OAuth 2.0 provider's details.
const CLIENT_ID        = 'YOUR_CLIENT_ID';
const OAUTH_BASE_URL   = 'https://auth.example.com/oauth2';
const USERINFO_URL     = 'https://auth.example.com/oidc/userinfo';
const REDIRECT_URI     = 'https://your-portal.example.com/api/login';
const STORAGE_KEY      = 'replay_access_token';
// Input name: OpenAPI security scheme id + suffix.
// For a scheme id 'bearerAuth' with type http/bearer, the suffix is '_token'.
const TOKEN_INPUT_NAME = 'bearerAuth_token';
// Used when the page selects no environment. Replay creates an environment for an unknown name.
const FALLBACK_ENV_NAME = 'Authorized';

// Pre-check: avoids a network call for clearly-expired JWTs.
function isJwtExpired(token: string): boolean {
  try {
    const b64 = token.split('.')[1].replace(/-/g, '+').replace(/_/g, '/');
    const { exp } = JSON.parse(atob(b64)) as { exp?: number };
    return typeof exp === 'number' && exp * 1000 <= Date.now();
  } catch {
    return false;
  }
}

// Validates the token against the OIDC UserInfo endpoint.
// Returns false if expired, revoked, or the network request fails.
async function isTokenValid(token: string): Promise<boolean> {
  if (isJwtExpired(token)) return false;
  try {
    const res = await fetch(USERINFO_URL, {
      headers: { Authorization: `Bearer ${token}` },
    });
    return res.ok;
  } catch {
    return false;
  }
}

const slideIn = keyframes`
  from { transform: translateX(100%); }
  to   { transform: translateX(0); }
`;

const spin = keyframes`
  to { transform: rotate(360deg); }
`;

const Spinner = styled.div`
  width: 32px;
  height: 32px;
  border: 3px solid var(--text-color-secondary, #888);
  border-bottom-color: transparent;
  border-radius: 50%;
  animation: ${spin} 0.8s linear infinite;
`;

const OverlayWrapper = styled.div`
  position: fixed;
  inset: 0;
  background: rgba(0, 0, 0, 0.35);
  display: flex;
  justify-content: flex-end;
  z-index: var(--z-index-overlay);
`;

const Panel = styled.div`
  width: 440px;
  height: 100%;
  background: var(--bg-color, #fff);
  display: flex;
  flex-direction: column;
  align-items: center;
  justify-content: center;
  padding: 48px 36px;
  gap: 20px;
  box-shadow: -4px 0 32px rgba(0, 0, 0, 0.14);
  animation: ${slideIn} 0.3s ease-out;
`;

// Matches Replay's own overlay close button, which sits on the backdrop next to the panel.
const CloseButton = styled.button`
  position: relative;
  right: var(--spacing-sm);
  top: var(--spacing-sm);
  align-self: flex-start;
  display: flex;
  justify-content: center;
  align-items: center;
  width: 24px;
  height: 24px;
  padding: 0;
  border: none;
  border-radius: var(--border-radius-md);
  background-color: var(--button-bg-color-secondary);
  cursor: pointer;
`;

const CloseButtonIcon = styled(CloseIcon)`
  width: 14px;
  height: 14px;
`;

// Always mounted at the same tree position across 'checking'/'authorizing'/'ready' so
// React never unmounts+remounts `children` — only its display toggles. Not rendered at
// all during 'gate'.
const ChildrenWrapper = styled.div<{ $hidden: boolean }>`
  display: ${({ $hidden }) => ($hidden ? 'none' : 'contents')};
`;

type Phase = 'checking' | 'gate' | 'authorizing' | 'ready';

export function ReplayGate({
  setEnvironmentValues,
  setSelectedEnvironment,
  selectedEnvironment,
  apiId,
  onClose,
  children,
}: ReplayGateProps) {
  // Starts at 'checking', not 'gate' — otherwise the sign-in button flashes on
  // screen for returning users while the stored token is still being validated.
  const [phase, setPhase] = useState<Phase>('checking');
  const [authUrl, setAuthUrl] = useState('');
  const popupRef = useRef<Window | null>(null);
  const channelRef = useRef<BroadcastChannel | null>(null);
  // Scope the stored token per API so different APIs in the same catalog don't
  // share (or overwrite) each other's credentials.
  const storageKey = apiId ? `${STORAGE_KEY}_${apiId}` : STORAGE_KEY;

  const startAuth = useCallback(() => {
    const state = crypto.randomUUID();
    const url =
      `${OAUTH_BASE_URL}/auth` +
      `?client_id=${encodeURIComponent(CLIENT_ID)}` +
      `&redirect_uri=${encodeURIComponent(REDIRECT_URI)}` +
      `&response_type=code&scope=openid+email+offline&state=${state}`;

    setAuthUrl(url);
    popupRef.current = window.open(url, '_blank');
    setPhase('authorizing');

    channelRef.current?.close();
    const channel = new BroadcastChannel('replay-auth');
    channelRef.current = channel;

    channel.onmessage = (event: MessageEvent) => {
      if (event.data?.type !== 'REPLAY_AUTH_DONE' || event.data.state !== state) return;
      channel.close();
      channelRef.current = null;
      popupRef.current?.close();
      popupRef.current = null;

      const token: string = event.data.access_token;
      localStorage.setItem(storageKey, token);

      // When the page selects no environment, name one anyway: Replay creates it on demand.
      const targetEnvironment = selectedEnvironment || FALLBACK_ENV_NAME;

      setEnvironmentValues(targetEnvironment, {
        [TOKEN_INPUT_NAME]: { value: token, isSecret: true },
      });
      setSelectedEnvironment(targetEnvironment);
      setPhase('ready');
    };
  }, [setEnvironmentValues, setSelectedEnvironment, selectedEnvironment, storageKey]);

  // On mount: restore a valid stored token, or start auth automatically.
  useEffect(() => {
    (async () => {
      const stored = localStorage.getItem(storageKey);
      if (stored && (await isTokenValid(stored))) {
        // When the page selects no environment, name one anyway: Replay creates it on demand.
        const targetEnvironment = selectedEnvironment || FALLBACK_ENV_NAME;

        setEnvironmentValues(targetEnvironment, {
          [TOKEN_INPUT_NAME]: { value: stored, isSecret: true },
        });
        setSelectedEnvironment(targetEnvironment);
        setPhase('ready');
      } else {
        localStorage.removeItem(storageKey);
        setPhase('gate');
      }
    })();
    // eslint-disable-next-line react-hooks/exhaustive-deps
  }, []);

  useEffect(() => {
    return () => { channelRef.current?.close(); };
  }, []);

  return (
    <>
      {phase !== 'gate' && (
        <ChildrenWrapper $hidden={phase !== 'ready'}>{children}</ChildrenWrapper>
      )}

      {phase !== 'ready' && (
        <OverlayWrapper
          onClick={(event) => {
            // A click on the backdrop itself closes Replay; clicks inside the panel don't.
            if (event.target === event.currentTarget) onClose();
          }}
        >
          <CloseButton aria-label="Close" onClick={onClose}>
            <CloseButtonIcon />
          </CloseButton>

          <Panel>
            {phase === 'checking' && <Spinner />}

            {phase === 'gate' && (
              <>
                <h2>Sign in to try it</h2>
                <p>Sign in to send live API requests.</p>
                <button onClick={startAuth}>Sign in</button>
              </>
            )}
            {phase === 'authorizing' && (
              <>
                <h2>Complete sign-in</h2>
                <p>A sign-in window has opened. Complete sign-in to continue.</p>
                <button
                  onClick={() => {
                    if (popupRef.current && !popupRef.current.closed) {
                      popupRef.current.focus();
                    } else {
                      popupRef.current = window.open(authUrl, 'auth-popup', 'width=520,height=680');
                    }
                  }}
                >
                  Re-open sign-in window
                </button>
              </>
            )}
          </Panel>
        </OverlayWrapper>
      )}
    </>
  );
}

1. ReplayGate opens the authorization URL in a popup window.
2. The user signs in and the identity provider redirects the popup to your REDIRECT_URI.
3. The @api/login.get.ts function exchanges the authorization code for an access token and returns an HTML page.
4. That page posts the token to the opener via BroadcastChannel and closes the popup.
5. ReplayGate receives the token, calls setEnvironmentValues and setSelectedEnvironment, and renders children.

ReplayTopBarActions renders custom UI in Replay's top bar, next to the environment switcher. The default implementation renders nothing. Eject it to add a sign-out button, a multi-account switcher, or an account indicator.

npx @redocly/cli eject component 'ReplayTopBarActions/ReplayTopBarActions.tsx'

import React from 'react';
import type { ReplayTopBarActionsProps } from '@redocly/theme/components/ReplayTopBarActions/ReplayTopBarActions';

const STORAGE_KEY     = 'replay_access_token';
const TOKEN_INPUT_NAME = 'bearerAuth_token';

export function ReplayTopBarActions({
  environments,
  setEnvironmentValues,
  apiId,
}: ReplayTopBarActionsProps) {
  const handleSignOut = () => {
    localStorage.removeItem(apiId ? `${STORAGE_KEY}_${apiId}` : STORAGE_KEY);
    for (const env of environments) {
      setEnvironmentValues(env.name, { [TOKEN_INPUT_NAME]: '' });
    }
    window.location.reload();
  };

  return (
    <button onClick={handleSignOut} style={{ padding: '6px 12px' }}>
      Sign out
    </button>
  );
}

Passing an empty string ('') for a token input clears the value in Replay's environment store — the same as a user manually deleting the field.

ReplaySecuritySchemeActions renders inside each security scheme card in Replay's Security tab. The default implementation renders nothing.

You can offer users a way to supply a credential inside security scheme cards in Replay's Security tab. Eject the ReplaySecuritySchemeActions component and configure it.

For example, add a sign-in button for your identity provider. Alternatively, you can add a link to the page that issues API keys, or a note naming the credential the scheme takes.

Unlike ReplayGate, it doesn't restrict access. Users reach every operation as usual, and the card offers a way to fill the credential it needs.

Replay renders the component only for schemes that take a single credential. Basic and digest authentication take a username and a password, so their cards render no slot.

npx @redocly/cli eject component 'ReplaySecuritySchemeActions/ReplaySecuritySchemeActions.tsx'

Your component receives every card, decides where to act, and returns null everywhere else. Narrow the offer by any of the following, and combine them as you need.

The following example offers a sign-in button on OAuth 2.0 cards, and a sign-out button once the card holds a token. It makes the offer for one API only, so the other APIs in a catalog keep their default cards. This example reuses the @api/login.get.ts callback page from the ReplayGate example above, which posts the token back over BroadcastChannel.

import React from 'react';
import type {
  ReplaySecurityType,
  ReplaySecuritySchemeActionsProps,
} from '@redocly/theme/components/ReplaySecuritySchemeActions/ReplaySecuritySchemeActions';

const AUTH_URL = 'https://auth.example.com/oauth2/auth?client_id=YOUR_CLIENT_ID&response_type=code';
const PAYMENTS_API_ID = 'payments-api';
// Environment names come from the servers in your API description.
const LIVE_SERVER = 'Production server';
// An access token fits these two scheme types and no others.
const TOKEN_TYPES = new Set<ReplaySecurityType>(['oauth2', 'openIdConnect']);

// Remember the token this component issued, so a token a user pastes is left alone.
const ISSUED_TOKEN_KEY = 'replay-issued-token';

export function ReplaySecuritySchemeActions({
  securityType,
  environment,
  value,
  setValue,
  apiId,
}: ReplaySecuritySchemeActionsProps) {
  const handleSignIn = () => {
    const state = crypto.randomUUID();
    const channel = new BroadcastChannel('replay-auth');

    channel.onmessage = (event: MessageEvent) => {
      if (event.data?.type !== 'REPLAY_AUTH_DONE' || event.data.state !== state) return;
      channel.close();
      sessionStorage.setItem(ISSUED_TOKEN_KEY, event.data.access_token);
      setValue(event.data.access_token);
    };

    window.open(`${AUTH_URL}&state=${state}`, 'replay-auth', 'width=520,height=680');
  };

  if (apiId !== PAYMENTS_API_ID || environment !== LIVE_SERVER) {
    return null;
  }

  if (!TOKEN_TYPES.has(securityType)) {
    return null;
  }

  return value && value === sessionStorage.getItem(ISSUED_TOKEN_KEY) ? (
    <button
      onClick={() => {
        sessionStorage.removeItem(ISSUED_TOKEN_KEY);
        setValue('');
      }}
    >
      Sign out
    </button>
  ) : (
    <button onClick={handleSignIn}>Sign in</button>
  );
}

Session storage outlives the card, which Replay unmounts when a user switches operation, and it carries the token across a page reload. It also ends with the browser tab.

Returning null leaves the card exactly as Replay renders it by default. A catalog with several APIs reaches this component for every one of them, so match on apiId when the credential belongs to a single API. Narrowing by operationId or by schemeId takes the same shape: one more check before the component returns anything.

Ejecting ReplayGate, ReplayTopBarActions, and ReplaySecuritySchemeActions is useful for:

• SSO enforcement: require users to sign in with your company's identity provider before using Replay
• Token pre-fill: silently inject a stored token so users don't need to paste credentials manually
• Multi-environment auth: select different environments or token scopes based on the signed-in user's role
• Session management: add a sign-out button or session expiration indicator inside Replay
• Credential handoff: offer sign-in on the security scheme card itself, so users fill a credential without leaving the operation

• Configure dynamic API data for Replay - Fetch tokens and other request values dynamically using the useConfigureReplay hook
• Configure request values - Set static request values for headers, parameters, and security details in your OpenAPI descriptions
• API functions reference - Function signature, routing, context helpers, and access control
• Eject components - Learn to eject and customize built-in components
• Extend with code - Discover all customization options for your project