Authentication

Sign in to the BankSync CLI with a browser OAuth flow or an API key, use the BANKSYNC_API_KEY env var, manage profiles, and understand where credentials are stored.

3 min read

On this page

Log in
Log in with an API key
The BANKSYNCAPIKEY environment variable
Check who you are
Log out
Profiles
Where credentials are stored
Next steps

The CLI supports two ways to authenticate. Run banksync login with no flags to sign in through your browser using OAuth 2.1 (Authorization Code with PKCE over a loopback redirect); there is no key to copy. For CI, containers, scripts, and AI agents, use an API key instead by passing --api-key or setting BANKSYNC_API_KEY. An API key is the same credential the REST API and MCP server use, so a key that works for one works for all three.

Store a scoped API key, verify the workspace, and use the CLI for repeatable terminal workflows.

API keys are created in the dashboard

The CLI never creates or revokes keys. Create one in the app under Settings > Developers, choosing the least-privilege scopes the command needs. See the API keys guide for scopes, expiration, and rotation. Every key starts with the bsk_ prefix.

Log in#

Run login with no flags to sign in through your browser. The CLI starts a temporary loopback listener, opens the BankSync authorization page, and finishes once you approve:

Shell

banksync login

Opening your browser to authorize BankSync CLI.If it does not open, visit this URL:  https://auth.banksync.io/authorize?...Waiting for approval...Logged in to Acme Inc (profile: default).

On a headless or SSH host with no browser, add --no-browser to print the URL so you can open it on another device:

Shell

banksync login --no-browser

Log in with an API key#

For CI, scripts, and agents, authenticate with an API key instead of the browser flow. The CLI validates it against your workspace, then stores it encrypted:

Shell

banksync login --api-key bsk_your_api_key_here

Only the bsk_ prefix is validated locally, so a mistyped or non-BankSync key is rejected before anything is stored. You can also skip login entirely and set BANKSYNC_API_KEY (see below).

The BANKSYNC_API_KEY environment variable#

For CI, containers, and one-off invocations you do not have to run login at all. Set BANKSYNC_API_KEY and every command picks it up:

Shell

export BANKSYNC_API_KEY="bsk_your_api_key_here"banksync banks list

You can also pass --api-key on a single command to override whatever is stored:

Shell

banksync banks list --api-key bsk_a_different_key

Credentials resolve in this precedence order:

The --api-key flag
The BANKSYNC_API_KEY environment variable
The stored credential for the active profile

Check who you are#

whoami shows the active credential's workspace, plan, and scopes:

Shell

banksync whoami

authMethod    apiKeyworkspaceId   ws_a1b2c3workspaceName Acme IncplanTier      professionalscopes        banks:read, feeds:read, jobs:write

Add --json for a machine-readable version, or run banksync status for a one-screen overview that also counts your banks and feeds.

Log out#

Remove the stored credential for the active profile:

Shell

banksync logout

This clears only the local credential; it does not revoke the key. To revoke a key, do it in the dashboard.

Profiles#

Profiles let you keep separate credentials and output preferences side by side, for example a personal workspace and a client workspace. Use --profile on any command, or set BANKSYNC_PROFILE:

Shell

banksync login --api-key bsk_client_key --profile clientbanksync banks list --profile client
export BANKSYNC_PROFILE=clientbanksync banks list

Profiles also carry non-sensitive display preferences (default output format, locale, time zone, color, telemetry). Manage them with banksync config:

Shell

banksync config set output json --profile clientbanksync config list

The environment cannot be changed

Config holds display preferences and profiles only. There is deliberately no base URL or environment setting: the released CLI always targets production. Attempting to set one is rejected.

Where credentials are stored#

Credentials live in an encrypted file, never in the plaintext config:

Directory: ~/.config/banksync on macOS and Linux (honoring XDG_CONFIG_HOME), and %APPDATA%\banksync on Windows. Override with BANKSYNC_CONFIG_DIR.
credentials.json: your credential, encrypted with AES-256-GCM and written with 0600 permissions (owner read/write only). The encryption key is derived at runtime from a machine-bound value (your host name and user) via scrypt; no key material is written to disk. Because the key is machine-bound, a credentials file copied or backed up to another machine or user account cannot be decrypted there.
config.json: profiles and display preferences (no secrets).

Secrets never touch the config file or logs. Under --verbose, the X-API-Key and Authorization headers are redacted.

API keys for headless use

The browser flow is the quickest way to sign in interactively, but API key auth remains the recommended path for CI, scripts, and AI agents, which run headless. Pass --api-key or set BANKSYNC_API_KEY.