Authentication

Learn how to authenticate with the BankSync API using API keys or bearer tokens. Understand scopes and permissions.

4 min read

On this page

API Key Authentication
Creating an API Key
Key Format
Code Example
Bearer Token Authentication
Scopes & Permissions

The BankSync API and MCP server support two authentication methods. Choose the one that fits your use case.

Minting the bsk_ key your requests authenticate with.

API Key Authentication#

The recommended method for server-side integrations, scripts, and MCP clients. Pass your API key in the X-API-Key header with every request.

X-API-Key: bsk_your_key_here

Creating an API Key#

To create an API key, open the BankSync app, click your workspace menu, and select Developers. From there you can name your key, choose which permission scopes it should have, and create it.

The Developer settings panel before any API keys exist, showing an empty API Keys list with a Create Key button. — The Developers panel before any keys are created.

The Create API Key dialog with a key name filled in and read and write permission scopes selected per resource. — Name the key and select only the permission scopes you need.

The newly created API key revealed once, with a copy button and a warning that the key will not be shown again. — Copy your API key now: it is shown only once.

Key Format#

All BankSync API keys begin with the bsk_ prefix followed by 44 random characters. For example:

bsk_a1B2c3D4e5F6g7H8i9J0k1L2m3N4o5P6q7R8s9T0u1V2

Code Example#

Shell

curl -X GET "https://api.banksync.io/v1/banks" \  -H "X-API-Key: bsk_your_api_key_here" \  -H "Content-Type: application/json"

JAVASCRIPT

const response = await fetch('https://api.banksync.io/v1/banks', {  headers: {    'X-API-Key': process.env.BANKSYNC_API_KEY,    'Content-Type': 'application/json',  },})

Python

import osimport requests
response = requests.get(    "https://api.banksync.io/v1/banks",    headers={        "X-API-Key": os.environ["BANKSYNC_API_KEY"],        "Content-Type": "application/json",    })

Security Best Practices

Store API keys in environment variables, never in source code

Never commit API keys to version control

Rotate keys regularly and revoke any that may be compromised

Use the minimum scopes required for your use case

Bearer Token Authentication#

For web app integrations where the user is already signed in to BankSync, you can use a session token as a bearer token. This method is primarily used by the BankSync web application itself.

Authorization: Bearer <session_token>X-Workspace-ID: <workspace_id>

When using bearer token authentication, you must also include the X-Workspace-ID header to specify which workspace you are operating on.

When to Use

Bearer token auth is best for browser-based apps where the user is already signed in to BankSync. For server-side scripts, CLI tools, and MCP clients, use API key authentication instead.

Scopes & Permissions#

API keys are scoped to specific permissions. When creating a key, select only the scopes you need.

Scope	Resource	Action	Access
`banks:read`	banks	read	View bank connections, accounts, transactions, balances, and holdings
`banks:write`	banks	write	Connect, modify, and disconnect bank connections. An installed app cannot permanently remove one.
`dashboards:read`	dashboards	read	View dashboards, widgets, queries, folders, and their query results over feed data. Not available to installed apps.
`dashboards:write`	dashboards	write	Create, modify, and delete dashboards, widgets, queries, and folders. Not available to installed apps.
`enrichments:read`	enrichments	read	View enrichment rules. An installed app sees only the rules it created.
`enrichments:write`	enrichments	write	Create, modify, and delete enrichment rules. An installed app reaches only the rules it created, and cannot write a rule that runs on every feed.
`feeds:read`	feeds	read	View sync feed configurations. An installed app sees only the feeds it created.
`feeds:write`	feeds	write	Create, modify, and delete sync feeds. An installed app reaches only the feeds it created.
`institutions:read`	institutions	read	Search banks and see which providers can connect them. Reference data about institutions — never your accounts or transactions
`integrations:read`	integrations	read	View connected destination integrations
`integrations:write`	integrations	write	Connect and remove destination integrations. An installed app can connect one but cannot remove any.
`jobs:read`	jobs	read	View sync history and job status. An installed app sees only the feeds it created.
`jobs:write`	jobs	write	Trigger manual syncs and cancel running jobs. An installed app reaches only the feeds it created.
`portals:read`	portals	read	View client portals and their membership. Not available to installed apps.
`portals:write`	portals	write	Create, modify, and delete client portals. Not available to installed apps.
`tables:read`	tables	read	View your tables, their fields, and the rows stored in them. An installed app sees only the tables it created.
`tables:write`	tables	write	Create and delete tables, change fields, and add, edit, or remove rows. An installed app reaches only the tables it created.
`workspaces:read`	workspaces	read	View workspace metadata, membership, and connected integrations
`workspaces:write`	workspaces	write	Modify workspace settings, members, and integrations

Note: Each operation enforces the exact scopes shown in its API reference. Grant both read and write only when a workflow performs both kinds of operation.

Note: API key management (creating and revoking keys) requires an authenticated session. API keys cannot self-manage: you must use the BankSync web app to create or revoke keys.

Use this page with your AI assistant

Every BankSync doc is available as plain Markdown for agents and LLMs.

View as Markdown Open in ChatGPT Open in Claude