# Authentication

> How to get a Virlo API key, send it with each request, and fix a rejected key.

Source: https://dev.virlo.ai/docs/authentication
Markdown: https://dev.virlo.ai/docs/authentication.md
Section: Start here

## About the Virlo API (applies to every page)

- Base URL: `https://api.virlo.ai/v1`. Every request needs the header `Authorization: Bearer YOUR_API_KEY` (keys start with `virlo_tkn_`).
- Responses are JSON inside a `data` field, except the `/v1/webhooks` endpoints, which return the object or array directly. Field names are snake_case.
- Prices are in US dollars from a prepaid balance. 1 credit = $0.01. The `X-Cost` response header on each successful response is the exact charge. Errors are free.
- Slow jobs return an ID. Check its status every 15 seconds (or whatever `retry_after_seconds` says) until `finalized` is `true`.
- All docs pages: https://dev.virlo.ai/llms.txt. Every page in one file: https://dev.virlo.ai/llms-full.txt. MCP server for AI assistants: https://dev.virlo.ai/api/mcp/mcp.

---

Your API key tells Virlo who is calling and which balance to charge.

**At a glance**

- **What it does:** Proves each request comes from your team.
- **You send:** `Authorization: Bearer YOUR_API_KEY` on every request.
- **You get back:** Your data, or `401` (key rejected).
- **Cost:** Free. Rejected requests are never charged.

## Get an API key

[Add funds](https://dev.virlo.ai/dashboard/billing), then click **Generate Key** on the [API keys](https://dev.virlo.ai/dashboard/api-keys) page. Copy the key now: it's shown only once.

- Keys start with `virlo_tkn_`. Each team shares up to 10 active keys.
- In the dashboard, only team owners and admins can generate or revoke keys.

## Who can see what

- **The whole team:** the balance, [lookups](https://dev.virlo.ai/docs/satellite), [tracked](https://dev.virlo.ai/docs/tracking) creators and videos, and [webhooks](https://dev.virlo.ai/docs/webhooks).
- **One person:** [Content Research Agents](https://dev.virlo.ai/docs/agents) are private to the person whose key created them. Teammates' keys get `404` (not found).

## Send your key

Run this free check in a terminal, replacing `YOUR_API_KEY` with your whole key:

**cURL request:**

```bash
curl https://api.virlo.ai/v1/account/balance \
  -H "Authorization: Bearer YOUR_API_KEY"
```

**Windows request:**

```powershell
curl.exe https://api.virlo.ai/v1/account/balance -H "Authorization: Bearer YOUR_API_KEY"
```

**JavaScript request:**

```js
async function main() {
  const response = await fetch('https://api.virlo.ai/v1/account/balance', {
    headers: { Authorization: 'Bearer YOUR_API_KEY' },
  })
  console.log(response.status, await response.json())
}

main()
```

**Python request:**

```python
import requests

response = requests.get(
    'https://api.virlo.ai/v1/account/balance',
    headers={'Authorization': 'Bearer YOUR_API_KEY'},
)
print(response.status_code, response.json())
```

**Response 200:**

```json
{
  "data": {
    "balance": "$25.00",
    "credits_remaining": 2500,
    "status": "active"
  }
}
```

**Response 401:**

```json
{
  "message": "Invalid or inactive API key",
  "error": "Unauthorized",
  "statusCode": 401,
  "code": "invalid_api_key"
}
```

## When a key is rejected

The `401` message tells you why:

- `API key is required` (`missing_api_key`): no key in the `Authorization` header. `x-api-key` and `?api_key=` aren't accepted.
- `Invalid API key format` (`invalid_api_key`): the key doesn't look like `virlo_tkn_...`. Usually `bearer` instead of `Bearer`, an extra space, or an empty key.
- `Invalid or inactive API key` (`invalid_api_key`): the key is mistyped, revoked, or has `virlo_tkn_` pasted twice.

Rapid retries from one computer with a missing or malformed key get briefly blocked (`429`, `too_many_requests`). Fix the key first.

## Keep your key safe

- Anyone with your key can spend your balance. Keep it out of chats, shared docs, web page code, and Git.
- If a key leaks, revoke it on the [API keys](https://dev.virlo.ai/dashboard/api-keys) page and generate a new one. Revoking cuts off everyone on your team using that key.

## Using the MCP server

AI assistants like Claude can use Virlo, paid from your team's balance.

- **Claude Desktop, claude.ai, Claude Code:** anyone who signs in gets a new team key (needs funds and under 10 active keys).
- **Cursor, VS Code, Windsurf, Codex:** paste an API key.

[Set up the MCP server](https://dev.virlo.ai/docs/mcp)

---

More in Start here:

- [Introduction](https://dev.virlo.ai/docs.md)
- [Quickstart](https://dev.virlo.ai/docs/quickstart.md)
- [Billing and pricing](https://dev.virlo.ai/docs/credits.md)
- [Glossary](https://dev.virlo.ai/docs/glossary.md)