> ## Documentation Index
> Fetch the complete documentation index at: https://bavlio.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> bav_live_ API keys, Bearer tokens, key rotation, x402 wallet auth as alternative.

Bavlio's SaaS API uses workspace-scoped API keys. Pass the key as a Bearer token in the `Authorization` header. Every request needs it.

## Key format

Bavlio API keys start with `bav_live_` followed by 43 URL-safe characters. The prefix lets you spot Bavlio keys in your secrets scanner. Treat the entire string as the secret.

```text Example theme={null}
bav_live_a1b2c3d4e5f6g7h8i9j0kLmNoPqRsTuVwXyZ
```

## Creating a key

<Steps>
  <Step title="Sign in to bavlio.com">
    Use the Google or email account on your workspace. [bavlio.com/login](https://bavlio.com/login).
  </Step>

  <Step title="Open Settings → API keys">
    Free-tier accounts cannot create keys; upgrade to a paid plan if you see a 403 on creation.
  </Step>

  <Step title="Click Create key, name it, copy immediately">
    Name describes the use (`production-agent`, `staging-worker`). The full value is shown **only once** on creation.
  </Step>

  <Step title="Store it as a secret in your runtime">
    Set as `BAVLIO_API_KEY` environment variable. Never commit it to source.
  </Step>
</Steps>

<Tip>
  **By design:** API keys cannot mint API keys. The endpoint that creates keys requires a logged-in dashboard session — this prevents a leaked key from cloning itself, and means agent provisioning always involves a human-in-the-loop initial setup.
</Tip>

## Sending the key

Pass the key as a Bearer token. Both the SaaS API and the BaviMail proxy under `/api/v1/bavimail/*` accept the same header.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET https://api.bavlio.com/api/v1/auth/me \
    -H "Authorization: Bearer bav_live_REPLACE_WITH_YOUR_KEY"
  ```

  ```python Python theme={null}
  import os, httpx
  client = httpx.Client(
      base_url="https://api.bavlio.com",
      headers={"Authorization": f"Bearer {os.environ['BAVLIO_API_KEY']}"},
  )
  me = client.get("/api/v1/auth/me").json()
  ```

  ```javascript Node theme={null}
  const response = await fetch("https://api.bavlio.com/api/v1/auth/me", {
    headers: { Authorization: `Bearer ${process.env.BAVLIO_API_KEY}` },
  });
  const me = await response.json();
  ```
</CodeGroup>

## Rotating a key

<Steps>
  <Step title="Create the new key first">
    Both old and new keys are valid in parallel — no downtime.
  </Step>

  <Step title="Deploy your runtime with the new key">
    Update the secret in your environment, restart workers.
  </Step>

  <Step title="Verify traffic is on the new key">
    Look at the dashboard **Last Used** column for both keys.
  </Step>

  <Step title="Revoke the old key">
    Revoked keys return HTTP 401 on every subsequent request. There is no undo — create a new key if needed.
  </Step>
</Steps>

## Scopes & permissions

<Warning>
  Today, all API keys grant **full workspace access** — there is no per-key scoping. Restricted (Stripe-style `rk_`) keys are on the roadmap. Until then, treat each key as workspace-admin and rotate aggressively if leaked.
</Warning>

## x402 wallet auth (alternative)

AI agents without a Bavlio account can hit a subset of Bavlio's data — email verification, email finder, LinkedIn URL discovery, prospect search — without an account, paying per call in USDC on Base mainnet via the x402 protocol. No signup, no API key, no subscription.

<CardGroup cols={2}>
  <Card title="x402 API Guide" icon="coins" href="https://bavlio.com/developers/x402">
    Full guide to wallet-paid endpoints. 5 endpoints at 0.003-0.012 USDC each.
  </Card>

  <Card title="Quickstart" icon="rocket" href="/quickstart">
    For agents using a regular `bav_live_` API key.
  </Card>
</CardGroup>