# Browser Tokens

_Use sensitive data in browser automations without exposing it to your application code, your agent, or your browser platform._

> **Alpha**
>
> Browser Tokens are in alpha and subject to change. Contact
>   [support@evervault.com](mailto:support@evervault.com) for access.

Browser Tokens let you use sensitive data in browser automation workflows without exposing that data to your application code, your agent, or your browser infrastructure. They're designed for agentic workflows and headless browser automations that need to enter payment cards, passwords, account credentials, API keys, or other sensitive values into third-party websites.

You send sensitive values to Evervault and receive format-preserving token values along with proxy credentials. Only those tokens are passed to your agent or browser. When the browser submits a request through Evervault's browser proxy, Evervault replaces the token values with the original plaintext over the wire.

## Why use browser tokens

Browser automations increasingly act on behalf of customers in real websites by logging into accounts, buying products, filling forms, and completing workflows. These flows often need sensitive data, which leaves three unappealing options.

- **Give the sensitive data to the agent.** Your application, prompt context, model provider, and browser automation code all become part of the sensitive data handling path.
- **Give the sensitive data to the browser platform.** Headless browser providers are strong at browser infrastructure, but they're rarely designed to handle PCI, credentials, or other regulated data.
- **Use network or issuer-specific agentic payment tokens.** These carry issuer, country, and card brand availability constraints, and each one needs its own integration and user experience.

Browser tokens are a compatibility layer instead. They work with any browser platform, and with any site where the sensitive value is ultimately submitted over the network. For payment flows, that value is usually a card number or CVV. For account access flows, it can be a password, recovery code, API key, or any other credential that shouldn't reach your agent, browser platform, logs, or automation code.

### Comparison to alternatives

| Approach | How it works | Trade-offs |
| --- | --- | --- |
| Raw card data in the agent or browser | The agent or browser automation receives the card number and CVV directly, and enters them into the site. | Simple, but it expands PCI scope to the agent, browser scripts, browser platform, logs, and surrounding infrastructure. Most model providers and browser automation platforms aren't PCI compliant, so this isn't a practical option. |
| Browser platform secret vault | The browser provider stores or injects sensitive values into the session. | Reduces prompt exposure, but puts the browser infrastructure provider in the sensitive data path. Values can still leak to the agent or automation scripts through the Chrome DevTools Protocol (CDP). |
| Issuer or network agentic payment token | A card network or issuer creates a payment-specific token for supported transactions. | Strong where available, but coverage depends on issuer, card brand, geography, and merchant acceptance. Each card brand needs a separate integration, and behavior varies between them. |
| Evervault Browser Tokens | Evervault returns format-preserving tokens, and reveals plaintext only through the browser proxy to allowed hostnames. | Works with existing browser platforms and merchant checkout flows, while keeping the agent and browser platform out of plaintext cardholder data handling. |

## How browser tokens work

1. **Collect and encrypt sensitive data.** Use [Card Collection](/cards/card-collection), a client-side or server-side SDK, or [Relay](/relay) to collect and encrypt sensitive values. These values can be considered non-sensitive and stored in your existing database. You can also provide plaintext values directly when that suits your integration.
2. **Create browser tokens.** Send the sensitive values to [`POST /browser-tokens`](#create-browser-tokens) with [policies](#policies) that define where the values can be revealed, and optional [egress configuration](#egress-configuration).
3. **Pass token values to your browser automation.** Evervault returns [format-preserving tokens](#token-formats) that look like the original data, so card tokens are Luhn-valid and preserve the original BIN.
4. **Launch your browser through Evervault's proxy.** Route the session through the [browser proxy](#browser-proxy) using the returned credentials. This works with platforms such as Browserbase, Browserless, Kernel, and Steel, as well as local Chromium and Playwright flows.
5. **Evervault replaces tokens over the wire.** Your browser enters token values into the page. Evervault scans requests sent through the proxy and replaces tokens with the original plaintext, but only for allowed destinations.

Evervault doesn't control, inspect, or interfere with the browser session itself beyond the proxy boundary.

## Security model

Browser tokens are designed so that sensitive data never needs to be exposed to:

- your application logic after token creation
- your agent
- your prompt context
- your browser automation script
- your browser platform

This applies to credentials as well as card data. The browser automation can fill a password token into a login form. The agent, model provider, browser platform, and workflow logs only ever see the token value.

Evervault never stores the plaintext or a server-side token mapping. Instead, the encrypted payload is embedded in a time-bound JSON Web Encryption (JWE) token, which is used as the authentication value for the browser proxy. The proxy uses the JWE to determine:

- which token values exist for the session
- what plaintext values they map to
- which hostnames can receive decrypted values
- when the token expires
- what egress configuration to use

If a request is sent to a hostname that isn't allowed by policy, the proxy behaves like a normal forward proxy and doesn't reveal the sensitive value.

## PCI scope reduction

When implemented correctly, browser tokens can keep your browser automation platform, agent, and backend automation infrastructure out of PCI scope. Those systems never transmit, process, or store cardholder data.

In this flow, cardholder data is collected and encrypted using Evervault-controlled collection surfaces before it reaches your automation stack. Your backend creates short-lived browser tokens from encrypted card data, receives format-preserving token values, and passes only those tokens to the agent or browser automation platform. The important boundary is that the systems driving the browser only ever handle tokens.

- **Your agent** sees and reasons over token values, not the card number or CVV.
- **Your browser automation code** fills token values into the page, not cardholder data.
- **Your browser automation platform** renders, stores, logs, and transmits token values through the browser session, not plaintext cardholder data.
- **Your backend infrastructure** stores encrypted values and creates scoped tokens, but doesn't need to store, log, or transmit plaintext cardholder data as part of the browser workflow.

Plaintext cardholder data is revealed only inside Evervault's browser proxy, and only when a request is sent to a destination hostname allowed by policy. The merchant or PSP receives the original cardholder data over the network. The agent, browser platform, and automation backend stay outside the cardholder data environment because they never touch the plaintext value.

To preserve this scope reduction, production integrations should:

1. Collect card data with [Card Collection](/cards/card-collection), an Evervault SDK, or [Relay](/relay).
2. Store only Evervault-encrypted card data in your systems.
3. Create short-lived browser tokens immediately before the automation session.
4. Pass only token values to the agent, browser runtime, logs, queues, and workflow systems.
5. Route the browser session through Evervault's browser proxy using the returned proxy credentials.
6. Scope reveal policies to the exact merchant or PSP hostnames the workflow needs.
7. Avoid logging, persisting, screenshotting, or otherwise exposing plaintext cardholder data anywhere in the automation stack.

## Create browser tokens

Create browser tokens just in time for a specific browser automation session.

```bash
curl -X POST 'https://api.evervault.com/browser-tokens' \
  -H 'Content-Type: application/json' \
  -u '<app_id>:<api_key>' \
  -d '{
    "data": [
      { "type": "card.number", "value": "ev:encrypted:..." },
      { "type": "card.cvv", "value": "ev:encrypted:..." },
      { "type": "password", "value": "ev:encrypted:..." }
    ],
    "ttl": 300,
    "policies": [
      {
        "action": "reveal",
        "destination": { "hostname": "www.example-merchant.com" }
      }
    ],
    "egress": {
      "type": "residential",
      "country": "us"
    }
  }'
```

**Request body**

- `data` `array` _(required)_ — The sensitive values to convert into browser-safe token values. Values can be Evervault-encrypted or plaintext.
  - `type` `string` _(required)_ — The semantic type of the value, such as `card.number`, `card.cvv`, `password`, `email`, or `phone`.
  - `value` `string` _(required)_ — The sensitive value. Use Evervault-encrypted values for production integrations.
- `policies` `array` _(required)_ — The rules that define where token values can be revealed as plaintext. See [Policies](#policies).
  - `action` `string` _(required)_ — The action to allow. Use `reveal`.
  - `destination.hostname` `string` _(required)_ — The hostname that can receive the plaintext value.
- `ttl` `number` — How long the tokens remain valid, in seconds. Defaults to `300`.
- `egress` `object` — The egress proxy configuration for the session. See [Egress configuration](#egress-configuration).
  - `type` `string` — Either `datacenter` or `residential`.
  - `country` `string` — The ISO country code to use for geographic routing.
  - `region` `string` — The region or state to route through, where supported.
  - `city` `string` — The city to route through, where supported.
  - `postalCode` `string` — The postal or ZIP code to route through, where supported.

The response contains a token for each value you sent, along with the proxy credentials for the session.

```json
{
  "data": [
    { "type": "card.number", "token": "4242424242424242" },
    { "type": "card.cvv", "token": "123" },
    { "type": "password", "token": "uG7q9vK2pL" }
  ],
  "proxy": {
    "server": "browser.relay.evervault.com:443",
    "username": "app_...",
    "password": "eyJ..."
  },
  "expiresAt": "2026-08-20T21:46:14Z"
}
```

The `proxy.password` is a time-bound encrypted JWE. Evervault doesn't store the mapping between token values and plaintext values.

## Token formats

Browser tokens are format-preserving where applicable, so they pass browser and merchant-side validation.

| Data type | Token format |
| --- | --- |
| Card number | Luhn-valid, and preserves the original card length and BIN where applicable. |
| Card CVV | Preserves digit length, including three-digit and four-digit CVVs. |
| Expiry date | Usually doesn't need tokenization. The expiry month and year can typically be passed through as non-sensitive values. |
| Email | Preserves email shape. |
| Phone number | Preserves country or region shape and digit count where applicable. |
| Password | Preserves a browser-compatible string shape. |

## Policies

Policies define where token values can be revealed as plaintext. Scope each policy as tightly as possible.

```json
{
  "action": "reveal",
  "destination": {
    "hostname": "payments.example.com"
  }
}
```

- A token is revealed only when the browser request is routed through Evervault's browser proxy, and the destination hostname matches an allowed policy.
- Multiple policies allow multiple destinations. Treat them as an allowlist.
- If a merchant checkout posts card data to a PSP, gateway, or embedded payment iframe, include the hostnames that actually receive the cardholder data.
- If the browser navigates or redirects to a hostname that isn't allowed, Evervault doesn't reveal the plaintext value to that hostname.
- Keep policies environment-specific. For example, use separate hostnames for sandbox and production payment flows.

Avoid broad policy rules. The intended production posture is to reveal only to the exact merchant, PSP, or gateway endpoints the workflow needs.

## Token lifecycle

Token values are useful only with the matching proxy credentials and policy context. After expiry, the proxy credentials can no longer be used to reveal the underlying plaintext.

1. Store the underlying sensitive value as Evervault-encrypted data.
2. Create browser tokens immediately before launching or attaching to the browser session.
3. Pass token values and proxy credentials only to the systems that need them for that session.
4. Use the shortest `ttl` that gives the automation enough time to complete.
5. Discard token values and proxy credentials once the workflow finishes or the `ttl` expires.

A workflow can take longer than expected because of login, multi-factor authentication (MFA), queueing, or human takeover. Set the `ttl` to cover that expected session duration rather than creating long-lived reusable tokens.

## Browser proxy

Browser tokens use Evervault's browser proxy, which is exposed as an HTTP `CONNECT` proxy.

```
browser.relay.evervault.com
```

When launching your browser, configure the platform's proxy settings with the credentials returned by the Browser Tokens API.

### Trust the Evervault CA

Because the browser proxy replaces token values with plaintext over the wire, the browser session must trust Evervault's certificate authority. Download the Evervault CA certificate from `https://browser.relay.evervault.com/ca.crt`, then install it as a trusted root CA in the browser runtime before routing traffic through the proxy. The exact setup depends on the browser provider.

- For local Chromium or Playwright, add the CA certificate to the operating system or browser trust store used by the automation runtime.
- For hosted browser platforms, configure the session to trust the Evervault CA if the platform supports custom root certificates.
- If the platform doesn't support custom root certificates, confirm whether it offers an equivalent certificate trust or proxy configuration path.

> **Don't bypass certificate errors**
>
> Without the Evervault CA in the browser's trust store, HTTPS pages can show
>   certificate errors or block requests routed through the proxy. Configure CA
>   trust explicitly instead of disabling certificate verification.

## Launch a browser session

The safest production pattern splits collection, token creation, and browser automation into separate steps. Your database stores encrypted card data, and your backend creates short-lived tokens. The agent and browser see only token values, so Evervault reveals plaintext to the allowed payment hostname alone.

### Hosted browser platforms

Most browser platforms let you provide proxy configuration when creating or connecting to a session. The exact launch configuration depends on your platform.

For example, using [Browserbase](https://browserbase.com) the integration would look like this:

Connect your automation to the session, then use the token values returned by Evervault in your browser steps.

## Credential and account access flows

Browser tokens aren't limited to payment data. The same pattern works anywhere a browser automation needs to submit a secret to a third-party website without exposing that secret to the agent or browser platform. Common credential use cases include:

- logging into a customer account with a password
- entering a recovery code or one-time backup code
- submitting an API key into a developer portal
- filling tax IDs, identity numbers, or other sensitive form fields
- completing internal admin workflows that need privileged credentials

The flow is the same as a payment flow. Collect or store the credential as an Evervault-encrypted value, then create a short-lived browser token scoped to the destination hostname. Give the agent and browser automation only the token value, and route the browser session through the browser proxy. Evervault reveals the plaintext credential over the wire to the allowed hostname.

For example, if an automation needs to log into `accounts.example.com`, the agent can navigate the site and fill a password token into the password field. The browser platform sees a browser-compatible token string, and Evervault reveals the original password only when the login request is sent through the proxy to the allowed hostname. This keeps credentials out of prompts, traces, screenshots, session recordings, browser-provider logs, and application logs, provided those systems only receive token values.

## Egress configuration

Browser tokens can be used with Evervault-managed egress IP configuration. Set the `egress` object when creating tokens to control the type and location of the IP the session routes through.

```json
{
  "egress": {
    "type": "residential",
    "country": "us",
    "city": "ny",
    "postalCode": "10013"
  }
}
```

Browser tokens only handle network egress. If your browser automation also needs timezone, locale, viewport, or geolocation alignment, configure those settings in your browser platform.

## Anti-bot compatibility

Evervault's proxy is designed to preserve compatibility with real browser traffic. It uses TLS and HTTP client impersonation techniques, so network fingerprints such as JA4 match expected browser behavior.

Evervault doesn't attempt to solve browser-level automation challenges such as CAPTCHAs, MFA, 3D Secure, or human-in-the-loop flows. Browser platforms often provide session takeover or human intervention features for those cases.

## Limitations

Browser tokens are a network-layer compatibility layer. They don't replace browser automation, fraud controls, or checkout orchestration.

- **Client-side encryption can require site-specific handling.** Some sites encrypt sensitive values in the browser before sending them over the network. Browser tokens still work where the site accepts raw values, but some PSP-specific flows need shims, which Evervault manages on your behalf.
- **3D Secure and MFA remain application and browser concerns.** Frictionless 3D Secure works normally, but challenge flows usually require user interruption or browser-platform session takeover.
- **Spending controls aren't enforced at the network layer.** Browser tokens can restrict where values are revealed, but transaction authorization stays with the issuer or payment processor.
- **Tokens are time-bound rather than single-use.** A token can be used more than once within its `ttl`, so keep the `ttl` as short as the workflow allows.
- **The browser session is outside Evervault's security boundary.** Evervault doesn't drive or inspect the browser session beyond proxying network traffic. Policies still ensure that sensitive data is never decrypted and revealed to a hostname you haven't explicitly allowed.

## Recommended integration pattern

For production use:

1. Collect card or sensitive data with [Card Collection](/cards/card-collection), an Evervault SDK, or [Relay](/relay).
2. Store only Evervault-encrypted values in your database.
3. Create short-lived browser tokens when starting a browser automation session.
4. Scope policies to the exact hostnames the workflow needs.
5. Use the shortest `ttl` that gives your automation enough time to complete.
6. Configure the browser session with Evervault's proxy credentials.
7. Pass only token values to the browser automation or agent.
8. Log which token categories were revealed, and to which destinations, after the session completes.