Banata

Start Here

API Keys

Learn where to use Banata API keys, how to scope them, how to rotate them, and how to structure keys across environments and teams.

Every Banata API request needs an API key.

In practice, your API key is how your own backend proves:

  • who is calling
  • what org the request belongs to
  • which permissions the caller should have

Where API keys belong

Use API keys on the server side.

Good places:

  • your backend app
  • job workers
  • internal admin tools
  • CI and automated test systems

Bad places:

  • browser-based frontend code
  • mobile apps
  • any client code you do not fully control

Using a key with the SDK

ts
import { BanataSandbox } from "@banata-boxes/sdk";
 
const banata = new BanataSandbox({
  apiKey: process.env.BANATA_API_KEY!,
  baseUrl: "https://api.boxes.banata.dev",
});

Using a key with raw HTTP

If you call the API directly, send:

text
Authorization: Bearer br_live_...

A good key strategy

Do not use one key for everything.

A better starting structure is:

  • one key for your production backend
  • one key for staging
  • one key for internal tools
  • one key for automated tests

Why this helps:

  • rotation is easier
  • incidents are easier to contain
  • audit trails are clearer
  • you can scope permissions more tightly per system

Understanding permissions

A key should only have the permissions its owner actually needs.

Common permissions:

PermissionUse it for
sandbox_sessions:createcreating new sandboxes
sandbox_sessions:readreading sandbox state, tasks, preview info, files, and runtime status
sandbox_sessions:deleteending sandboxes
sandbox_sessions:execrunning commands, sending agent tasks, managing files, and controlling runtime operations
org:billingreading usage and billing information
api_keys:managecreating, rotating, and revoking keys

Rotation strategy

Rotate keys:

  • on a schedule
  • after staff changes
  • after any suspected leak
  • when moving responsibilities between services

Safe rotation flow:

  1. create a new key
  2. deploy it to the target service
  3. verify that service is healthy
  4. revoke the old key

Storage and environment design

The most common pattern is:

  • store the key in your secret manager or environment config
  • inject it into your backend at runtime
  • never hardcode it in the repo

How this affects your app design

If your app has both a frontend and a backend:

  • the frontend should call your backend
  • your backend should call Banata

That keeps the API key under your control and gives you a clean place to:

  • validate user permissions
  • attach metadata
  • decide when to create tasks
  • receive webhooks

Related pages