---
title: "API keys"
description: "Create scoped BankSync API keys, copy the secret once, authenticate requests, and revoke keys."
section: "API"
canonical: "https://banksync.io/docs/api/api-keys"
---

An API key is a secret credential that gives programmatic access to your workspace through the BankSync REST API and the MCP server. Each key carries a fixed set of permission scopes you choose at creation, so a script or AI agent gets exactly the access it needs and nothing more.

[![Creating an API key in the BankSync app: opening Settings, the Developer section, the API Keys panel, naming the key Production MCP Server, selecting the feeds and banks scopes, revealing and copying the bsk\_ key once, and the note that one key works for both the REST API and MCP clients.](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 an API key in the BankSync app: opening Settings, the Developer section, the API Keys panel, naming the key Production MCP Server, selecting the feeds and banks scopes, revealing and copying the bsk\_ key once, and the note that one key works for both the REST API and MCP clients.](https://cdn.banksync.io/videos/api-keys-and-mcp.76edc41d298a567a.mp4)

> **Before you start:** You need the Admin or Owner role in the workspace to create or revoke keys. API keys are
> managed only from the BankSync web app: a key cannot create or revoke other keys. API access also
> depends on your plan, so if you see an "isn't included on your plan" banner on the API Keys panel,
> upgrade before creating a key.

## What an API key looks like

Every key starts with the `bsk_` prefix followed by a long random string. The full secret is shown to you exactly once, at the moment of creation. After that, BankSync only ever displays the first 8 characters (the **key prefix**, for example `bsk_a3f5`) so you can identify the key in lists without exposing the secret.

```text
bsk_a1B2c3D4e5F6g7H8i9J0k1L2m3N4o5P6q7R8s9T0u1V2
```

## Create an API key

**Create a key**

1. **Open Developer settings** — Click your workspace menu, then select Developers. The API Keys panel opens and lists
   any existing keys, or shows "No API keys yet" if you have none.
2. **Start a new key** — Click Create Key. The create view opens with fields for the key name, expiration, and
   permissions.
3. **Name the key** — Type a descriptive name in Key Name, for example "Production MCP Server". The name is only a
   label to help you recognize the key later.
4. **Choose an expiration** — Under Expiration, pick one of 30 days, 60 days, 90 days, 1 year, or Never.
   Short-lived keys reduce the blast radius if a secret leaks.
5. **Select scopes** — Under Permissions, toggle the read and write actions you need per resource. Use Select
   all only if the key genuinely needs full access. You must select at least one permission to
   continue.
6. **Create it** — Click Create API Key. The reveal view appears with the full secret.
7. **Copy the secret immediately** — Click the copy icon (or select the text) and store the key somewhere safe. The screen warns that
   this is the only time it will be shown and it cannot be retrieved later. Click Done to
   return to the list.

![BankSync API Keys panel listing two keys: Production MCP Server with feeds and jobs read plus write scopes, and Reporting (read-only) with only read scopes, each showing the masked key prefix, an Active badge, created and expiry dates, and a revoke action, with a Create Key button below](https://cdn.banksync.io/screenshots/api/api-keys.c4c64ac282611b4f.png "The API Keys panel: each key shows its name, masked prefix, scopes (read in blue, write in amber), status, and dates.")

> **The full key is shown only once:** 'BankSync stores only a SHA-256 hash of your key, never the plaintext. If you close the reveal view ("Done") without copying the secret, you cannot recover it: revoke the key and create a new one.'

## The scopes model

Scopes follow a `resource:action` pattern (Stripe-style). There are two actions, `read` and `write`, across the resources below. Grant the least privilege a key needs: a reporting script usually needs only read scopes, while an automation that triggers syncs or creates feeds needs the matching write scopes.

| Resource     | Read scope          | Write scope          | Read access                           | Write access                                  |
| ------------ | ------------------- | -------------------- | ------------------------------------- | --------------------------------------------- |
| Workspaces   | `workspaces:read`   | `workspaces:write`   | Workspace metadata and membership     | Modify workspace settings and members         |
| Banks        | `banks:read`        | `banks:write`        | List and get banks and accounts       | Connect and delete banks                      |
| Feeds        | `feeds:read`        | `feeds:write`        | List and get feeds                    | Create, update, delete feeds                  |
| Jobs         | `jobs:read`         | `jobs:write`         | List and get jobs                     | Trigger syncs, cancel jobs                    |
| Enrichments  | `enrichments:read`  | `enrichments:write`  | List and get enrichment rules         | Create, update, delete rules                  |
| Dashboards   | `dashboards:read`   | `dashboards:write`   | View dashboards, widgets, and queries | Create, update, delete dashboards and widgets |
| Portals      | `portals:read`      | `portals:write`      | View client portals                   | Create, update, delete client portals         |
| Integrations | `integrations:read` | `integrations:write` | View destination integrations         | Connect and remove integrations               |

> **Scopes and least privilege:** 'A write scope authorizes write actions for its resource. Some write paths read the resource first, so the safe choice is to grant both the read and write scope for any resource a key needs to modify. The dashboards, portals, and integrations scopes cover the corresponding surfaces of the app and MCP server.'

## Use the key

Pass the key in the `X-API-Key` header on every request. The base URL for the REST API is `https://api.banksync.io/v1`. Because a key is bound to a single workspace, you do not need to send a workspace header.

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

Store the key in an environment variable rather than pasting it inline so it never lands in your shell history or source control.

```bash
export BANKSYNC_API_KEY="bsk_your_api_key_here"

curl -X GET "https://api.banksync.io/v1/banks" \
  -H "X-API-Key: $BANKSYNC_API_KEY"
```

The same key authenticates the MCP server, so an AI client configured with it can call BankSync tools within the scopes you granted. See the [MCP server guide](/docs/mcp/overview) for client setup.

## List your keys

On the **API Keys** panel, each existing key shows its name, the key prefix (for example `bsk_a3f5...`), an **Active** badge, the granted scopes (read in blue, write in amber, grouped by resource), the creation date, and the expiry. The full secret is never shown again, by design.

```bash
curl -X GET "https://api.banksync.io/v1/workspaces/WORKSPACE_ID/api-keys" \
  -H "Authorization: Bearer YOUR_SESSION_TOKEN" \
  -H "X-Workspace-ID: WORKSPACE_ID"
```

> **Why this call uses a session token:** 'Creating and revoking keys are session-only: they need a signed-in Bearer token plus the X-Workspace-ID header, not an X-API-Key, because a key cannot mint or revoke other keys. Listing keys also accepts a key that has \`workspaces:read\`. In practice you do all key management from the web app.'

## Revoke a key

**Revoke a key**

1. **Find the key** — On the API Keys panel, locate the key by its name and prefix.
2. **Start revocation** — Click the trash icon on the key's row (titled "Revoke key"). An inline Cancel / Revoke
   confirmation appears.
3. **Confirm** — Click Revoke. The key is invalidated immediately and removed from the active list.

Revocation takes effect at once: any request using a revoked key gets a `401 Invalid or expired API key` response. There is no grace period and no way to reactivate, so rotate by creating a new key first, switching your integration over, then revoking the old one.

## Security best practices

- **Store secrets safely** — Keep keys in environment variables or a secrets manager. Never commit them to version control or
  hard-code them.
- **Least privilege** — Grant only the scopes a key needs. A read-only reporting job should not hold any write scope.
- **Rotate regularly** — Set an expiration and rotate keys on a schedule. Create the replacement, cut over, then revoke
  the old key.
- **Revoke leaked keys** — If a key is exposed in logs, a screenshot, or a repo, revoke it immediately and issue a new one.

## Confirm it worked

Make a read request scoped to a permission you granted. A `200 OK` with a JSON body confirms the key is valid and correctly scoped.

```bash
curl -i -X GET "https://api.banksync.io/v1/banks" \
  -H "X-API-Key: $BANKSYNC_API_KEY"
```

| Response           | Meaning                                                                                                     |
| ------------------ | ----------------------------------------------------------------------------------------------------------- |
| `200 OK`           | The key is valid and has the scope for this resource.                                                       |
| `401 Unauthorized` | The key is missing, mistyped, expired, or revoked.                                                          |
| `403 Forbidden`    | The key is valid but lacks the required scope for this operation, or your plan does not include API access. |

After revoking, repeat the same request: a `401` confirms the key is dead.

## Troubleshooting

> **Every request returns 403 right after creating a key:** 'This usually means your plan does not include API or MCP access (you would have seen a lock banner on the API Keys panel), or the key is missing a scope the operation needs (remember write needs read too). Check the granted scopes in the list, and confirm your plan on the billing page.'

- **`401` on a brand new key:** make sure you copied the full secret from the reveal view, with no truncation or trailing whitespace, and that you are sending it in `X-API-Key`, not `Authorization`.
- **Lost the secret:** it cannot be recovered. Revoke the key and create a new one.
- **Need to create or revoke keys via API:** you cannot. Key creation and revocation require a signed-in session in the web app (listing keys is available with a `workspaces:read` key).

## Next steps

- [Authentication](/docs/api/authentication): full reference for API key and bearer token auth, headers, and scopes.
- [REST API guide](/docs/api/rest-api): endpoints, request and response shapes, and pagination.
- [MCP server guide](/docs/mcp/overview): connect an AI client to BankSync using your API key.