Authentication

Chainabit uses JWT bearer tokens for authenticated API requests. There are two main ways to authenticate:

1. Browser login — the chainabit auth login command opens a device-approval page in your browser.
2. Developer tokens — scoped, time-bounded credentials for CI/CD pipelines and automation scripts.

---

CLI: Browser Login (Recommended)

Run chainabit auth login with no flags. The CLI opens your browser automatically.

chainabit auth login

What happens:

1. The CLI contacts the Chainabit API and receives a short-lived approval code.
2. Your browser opens the device-approval page with the code pre-filled.
3. Sign in (or you are already signed in) and click Approve login.
4. The CLI detects the approval and saves your session to ~/.chainabit/config.json.

If the browser does not open automatically, copy the URL printed in the terminal and open it manually.

Non-interactive / headless login

Use a developer token (see below) for scripts and CI:

export CHAINABIT_TOKEN=YOUR_DEVELOPER_TOKEN
chainabit workspace use ws_yourworkspace
chainabit ai session list

---

CLI: Developer Tokens for CI/CD

Developer tokens are personal, scoped credentials you create once and store in your environment. They are the recommended approach for automation and CLI workflows.

Create a developer token

chainabit auth keys create "github-actions" --ttl 90 --scope execution:run

The raw token is shown once only. Copy it immediately.

API key created: YOUR_DEVELOPER_TOKEN
This key will not be shown again.

To use in CI/CD:
  export CHAINABIT_TOKEN=YOUR_DEVELOPER_TOKEN
  chainabit workspace use <workspace-id>

Optional flags:

chainabit auth keys create "wallet-bot" --ttl 30 --scope wallet:read --scope execution:run
chainabit auth keys create "account-bot" --ttl 30 --account <account-uuid> --scope execution:run

Use the token

Set CHAINABIT_TOKEN in your CI environment (GitHub Actions secret, .env file, etc.):

CHAINABIT_TOKEN=YOUR_DEVELOPER_TOKEN chainabit ai session list

The CLI validates cbt_live_... tokens directly against the API. When talking to older servers it can still fall back to the legacy exchange flow automatically.

Manage tokens

chainabit auth keys list
chainabit auth keys revoke <id>

---

API: Password Login

Direct API access with username/password (requires a captcha token from supported frontends):

curl -X POST "$BASE_URL/auth/login" \
  -H "Content-Type: application/json" \
  -H "x-turnstile-token: <captcha-token>" \
  -d '{
    "identifier": "you@example.com",
    "password": "yourPassword123"
  }'

Response:

{
  "data": {
    "userId": "uuid",
    "email": "you@example.com",
    "tokens": {
      "accessToken": "eyJ...",
      "refreshToken": "eyJ...",
      "expiresIn": 900,
      "tokenType": "bearer"
    }
  }
}

expiresIn is the access token's lifetime in seconds (900 by default — 15 minutes); use the refresh token to get a new one rather than hardcoding this value. The real response also includes additional account context (subscription, entitlements, profile, workspaces, preferences) for first-party Chainabit clients — treat only userId, email, and tokens as the stable, documented contract; the rest is not versioned for external integrations and may change shape without notice.

---

Use the Access Token

curl "$BASE_URL/ai/sessions" \
  -H "Authorization: Bearer $TOKEN"

---

Refresh a Session

chainabit auth refresh

Or via API:

curl -X POST "$BASE_URL/auth/refresh" \
  -H "Content-Type: application/json" \
  -d '{"refreshToken":"'"$REFRESH_TOKEN"'"}'

Refresh tokens are single-use. Store the new refresh token returned in the response.

---

Environment Variables

Variable	Description	Example
CHAINABIT_TOKEN	Access token or developer token (cbt_live_...)	Pre-supply auth without logging in
CHAINABIT_BASE_URL	API base URL	https://api.chainabit.com/api/v1
CHAINABIT_APP_BASE_URL	Chainabit app origin	https://chainabit.com
CHAINABIT_WORKSPACE_ID	Default workspace ID	Auto-selects workspace

---

Related

• How to Authenticate
• Auth API Reference