API keys

Create scoped BankSync API keys, copy the secret once, authenticate requests, and revoke keys.

6 min read

On this page

What an API key looks like
Create an API key
The scopes model
Use the key
List your keys
Revoke a key
Security best practices
Confirm it worked
Troubleshooting
Next steps

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 a scoped API key, from Settings to the one-time reveal.

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.

bsk_a1B2c3D4e5F6g7H8i9J0k1L2m3N4o5P6q7R8s9T0u1V2

Create an API key#

Create a key

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.
Start a new key
Click Create Key. The create view opens with fields for the key name, expiration, and permissions.
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.
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.
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.
Create it
Click Create API Key. The reveal view appears with the full secret.
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 — 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.

Shell

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.

Shell

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

Shell

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

Find the key
On the API Keys panel, locate the key by its name and prefix.
Start revocation
Click the trash icon on the key's row (titled "Revoke key"). An inline Cancel / Revoke confirmation appears.
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.

Shell

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: full reference for API key and bearer token auth, headers, and scopes.
REST API guide: endpoints, request and response shapes, and pagination.
MCP server guide: connect an AI client to BankSync using your API key.

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