API Keys

Every request to the Banata API requires an API key. The key identifies your organization, enforces usage limits, and scopes all operations to your account.

Getting an API Key

From the Dashboard

1. Sign in to the Banata dashboard.
2. Navigate to API Keys in the sidebar.
3. Click Create new key.
4. Copy the key immediately — it is only shown once.

From the Seed Endpoint (Development)

During local development, you can generate a test API key using the seed endpoint. See the setup guide in the Banata dashboard for instructions.

Using Your API Key

Pass the key in the Authorization header on every request:

curl -X POST "https://api.boxes.banata.dev/v1/browsers" \
  -H "Authorization: Bearer br_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

In code:

const response = await fetch("https://api.boxes.banata.dev/v1/browsers", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.BANATA_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ weight: "light" }),
});

If the key is missing or invalid, the API returns 401 Invalid or missing API key.

Key Format

All Banata API keys use the prefix br_live_ followed by 32 random alphanumeric characters:

br_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6

The raw key value is never stored by Banata — only a SHA-256 hash is kept. This means:

• If you lose a key, you cannot retrieve it. Create a new one.
• Keys from one organization cannot access another organization's sessions or data.

Key Permissions

API keys can be scoped with specific permissions that control what operations they can perform. If no permissions are set on a key, it has full access to all endpoints.

Available permission scopes:

When creating keys through the dashboard, you can select which permissions to grant. A key with browser_sessions:create and browser_sessions:read can create and poll browser sessions but cannot delete them or access sandbox or billing endpoints.

Key Lifecycle

Expiration

Keys can be created with an optional expiration date. Expired keys are automatically rejected. If no expiration is set, the key remains valid until explicitly revoked.

Revocation

Revoked keys are immediately rejected on all endpoints. Revocation is permanent — a revoked key cannot be reinstated.

Last Used Tracking

Each key records when it was last used. You can view this in the dashboard to identify unused keys that should be revoked.

Security Practices

Store keys in environment variables

Never hard-code API keys in source code. Use environment variables or a secrets manager:

# .env (never commit this file)
BANATA_API_KEY=br_live_your_key_here

Use separate keys per service

If multiple services call the Banata API (your web app, a background worker, a CI pipeline), create a separate key for each. If one is compromised, revoke it without affecting the others.

Scope keys to minimum permissions

Create keys with only the permissions each service needs. A service that only creates and reads browser sessions should not have org:billing or api_keys:manage permissions.

Rotate keys periodically

To rotate a key safely:

1. Create a new key in the dashboard with the same permissions.
2. Deploy your services with the new key.
3. Verify everything works.
4. Revoke the old key in the dashboard.

Next Steps

• Quick Start — Use your API key to launch a browser session
• Browser Sessions — Create and configure browser sessions
• Sandboxes — Create and configure sandbox environments
• Rate Limits — Understand per-org rate limiting