---
title: "Authentication"
description: "Learn how to authenticate with the BankSync API using API keys or bearer tokens. Understand scopes and permissions."
section: "API"
canonical: "https://banksync.io/docs/api/authentication"
---

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

[![Creating the API key that authenticates your requests: opening Settings, the Developer section, creating a key named Production MCP Server with feeds and banks scopes, and copying the one-time bsk\_ key used as the Bearer token.](https://cdn.banksync.io/videos/api-keys-and-mcp.poster.a4bc2ee6ace134e3.png)](https://cdn.banksync.io/videos/api-keys-and-mcp.76edc41d298a567a.mp4)

[Watch: Creating the API key that authenticates your requests: opening Settings, the Developer section, creating a key named Production MCP Server with feeds and banks scopes, and copying the one-time bsk\_ key used as the Bearer token.](https://cdn.banksync.io/videos/api-keys-and-mcp.76edc41d298a567a.mp4)

## 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.

```text
X-API-Key: bsk_your_key_here
```

### Creating an API Key

To create an API key, open the [BankSync app](https://app.banksync.io), 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.](https://cdn.banksync.io/screenshots/api/keys-empty.5ea3b230ae5b39fe.png "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.](https://cdn.banksync.io/screenshots/api/create-key-filled.30cd75c657c6d210.png "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.](https://cdn.banksync.io/screenshots/api/key-revealed.7623162059957ddf.png "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:

```text
bsk_a1B2c3D4e5F6g7H8i9J0k1L2m3N4o5P6q7R8s9T0u1V2
```

### Code Example

```bash
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 os
import 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.

```text
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.

| Resource         | Read Scope         | Write Scope         | Read Access                                      | Write Access                     |
| ---------------- | ------------------ | ------------------- | ------------------------------------------------ | -------------------------------- |
| Banks & Accounts | `banks:read`       | `banks:write`       | List/get banks, accounts                         | Connect/delete banks             |
| Feeds            | `feeds:read`       | `feeds:write`       | List/get feeds                                   | Create/update/delete feeds       |
| Jobs & Syncs     | `jobs:read`        | `jobs:write`        | List/get jobs                                    | Trigger syncs, cancel jobs       |
| Enrichments      | `enrichments:read` | `enrichments:write` | List/get enrichments, preview rules              | Create/update/delete enrichments |
| Workspaces       | `workspaces:read`  | `workspaces:write`  | List workspaces, integrations, members, API keys | Delete integrations              |

> **Note:** Write operations require both read AND write scopes. For example, creating a feed requires both `feeds:read` and `feeds:write`.

> **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.