Authentication

Create your account, log in from the CLI, and get project API keys: fully self-serve.

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.

Request a login email

npx @banatie/cli signup [email protected]

Prefer not to use the terminal? Enter your email at banatie.app for the same result.

The email contains your organization slug and a one-time bnt_boot_ login token. Sign-up always returns the same neutral response and is rate-limited, so account state is never leaked.

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 auth login <org-slug> <bnt_boot-token>

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

Build your login command

Paste the values from your login email. Nothing leaves this page: the command is assembled locally.

Organization slugOne-time login token

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

Fill in both fields to get a command you can run as-is.

The CLI needs no install: npx @banatie/cli runs it directly (Node 18 or newer). The bnt_boot_ token works exactly once; if it expired, just request a new login email.

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):

Create a project

npx @banatie/cli 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

List projects

npx @banatie/cli 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. --root defaults to the current directory.

Connect this repo

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

Add .banatie/ to your .gitignore so the project link is not committed. Connecting doesn't mint a key: that's the next step.

Get a Project API Key

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

Issue an API key

npx @banatie/cli project issue-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:

Issue a key in a connected repo

npx @banatie/cli project issue-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

Product commands read your project key from BANATIE_API_KEY — the CLI auto-loads it from a local .env (written by project issue-key --write-env .env), so you just run the command:

Generate with your project key

npx @banatie/cli generate "a sunset over the ocean" --output-dir .

Keep your API key secure. Keep .env out of version control and never expose the key in client-side code. For direct HTTP calls the key goes in the X-API-Key header — see the API reference.

Key Types

Banatie uses two types of API keys:

Type	Permissions	Expiration	Use Case
`Project Key`	Image generation, uploads, images	90 days	Your application integration
`Master Key`	Full admin access, key management	Never expires	Server-side admin operations

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

Don't confuse API keys with your organization token: the org token goes in an Authorization: Bearer header and manages your account, while API keys go in X-API-Key and generate images. Need a fresh project key? Just run project issue-key again.

Managing Your Org Token

Four commands manage the stored organization token:

Org token management

npx @banatie/cli auth status --org acme   # show login state (token preview only)
npx @banatie/cli auth rotate --org acme   # replace the token; the old one stops working
npx @banatie/cli auth revoke --org acme   # invalidate the token on the server and log out
npx @banatie/cli auth logout --org acme   # 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:

Step 1: request deletion

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

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:

Step 2: confirm deletion

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

The confirmation step refuses to run non-interactively: it must be executed in a real terminal. Expired token? Re-run step 1 to get a new email.