Authentication

Overview

Banatie authentication has two layers. Your personal organization token (bnt_org_...) identifies you as the account owner: the CLI stores it locally and uses it to create and manage projects. Each project then has its own project API keys (sent via the X-API-Key header) that your applications use to generate images. You never handle the org token directly, and project keys never leave your side of the integration.

The whole flow takes a couple of minutes: request a login email, log in from the CLI, create a project, connect a local directory, and mint an API key. Every command below is covered in depth in the CLI reference.

Create Your Account

One command with your email: we create an organization for you and email you a one-time login command.

npx @banatie/cli signup [email protected]

The same request works without the CLI: enter your email at banatie.app or hit the public endpoint directly:

curl -X POST https://api.banatie.app/api/v1/org/bootstrap \
  -H "Content-Type: application/json" \
  -d '{"email": "[email protected]"}'

{
  "status": "email_sent",
  "message": "Check your email for the Banatie organization login command.",
  "nextActions": [
    {
      "type": "check_email",
      "description": "Run the one-time CLI command from the email to finish login."
    }
  ]
}

Log In From the CLI

Run the command from your login email. It exchanges the one-time token for a permanent organization token and stores it in ~/.banatie/config.json. The raw token is never printed: you'll only ever see a preview like bnt_org_...4f2a1c.

npx @banatie/cli org <org-slug> login <bnt_boot-token>

Or build your exact command right here from the values in your email:

npx @banatie/cli org <org-slug> login <bnt_boot-token>

Create a Project

Projects are the unit of API access: each has its own keys, storage, and usage. Create one with a slug (letters, numbers, and hyphens):

npx @banatie/cli org acme project new my-app

This creates the project and mints its first API key server-side in one atomic step: the CLI prints the key preview and the connect command for your repo.

List Your Projects

npx @banatie/cli org acme project list

Prints each project's slug, name, and creation date. Project keys are never included: key material only appears when you explicitly issue a key.

Connect a Local Directory

Link a local repository to a project. This writes a small .banatie/project.json file so later commands know which project this directory belongs to. --project-root defaults to the current directory.

npx @banatie/cli org acme project connect my-app --project-root .

Get a Project API Key

Mint a fresh API key and write it straight into your env file:

npx @banatie/cli org acme project issue-api-key my-app --write-env .env

Inside a connected directory there's an even shorter form: it reads .banatie/project.json and needs no org or project slug:

npx @banatie/cli issue-api-key --write-env .env

Both forms idempotently upsert BANATIE_API_KEY into the file. Without --write-env, the key is printed to stdout as BANATIE_API_KEY=bnt_... instead. Every call mints a new server-side key.

Using Your API Key

All API requests require the X-API-Key header:

curl -X POST https://api.banatie.app/api/v1/generations \
  -H "X-API-Key: your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "a sunset over the ocean"}'

Key Types

Banatie uses two types of API keys:

Project Keys are what project new and issue-api-key mint for you. Master Keys are for administrative operations: you probably don't need one.

Managing Your Org Token

Four commands manage the stored organization token:

npx @banatie/cli org acme auth status   # show login state (token preview only)
npx @banatie/cli org acme auth rotate   # replace the token; the old one stops working
npx @banatie/cli org acme auth revoke   # invalidate the token on the server and log out
npx @banatie/cli org acme auth logout   # remove the local login only

logout is local-only: the token stays valid on the server until you revoke or rotate it. If you suspect the token leaked, rotate immediately: the CLI stores the replacement and the old token is invalidated in the same call.

Deleting a Project

Deletion is destructive (it cascades to the project's keys and images), so it takes two explicit steps. First, request deletion, nothing is deleted yet:

npx @banatie/cli org acme project delete my-app

A one-time confirmation token is emailed to the organization owner. Run the command from that email: the CLI asks you to confirm interactively before anything is removed:

npx @banatie/cli org acme project delete my-app <one-time-token>

Next Steps