⌘K
sandbox.bankconnector.com API Reference

Managing companies & users

Audience: 🧑‍💼 Company Admin, 🔌 Integration Client (control-plane setup)

A company is the tenant: the organisation that holds the bank agreement. Each company is isolated, with its own payments, bank connections, users and API keys. An API key belongs to one company and cannot reach another.

Managing a company's users and keys is a control-plane action. You do it as a signed-in admin with a session token, not with an API key (see Authentication). The sandbox lets you try this flow end to end.

Step 1: Set the admin's password, then log in

POST /api/sandbox/provision returns a dashboardLogin object with the admin's email and a setPasswordUrl link (…/#setup_token=…, single-use, expires after 7 days; there is no other way back in for this account, so use it promptly). Open it in a browser to choose a password, or take the token from after #setup_token= and set one directly:

curl -X POST https://sandbox.bankconnector.com/api/auth/set-password \
  -H "Content-Type: application/json" \
  -d '{
    "token":    "…",
    "password": "a-strong-password"
  }'
# 200 { ok: true, email }

That account is the admin of your sandbox company. Log in to get a session. The response body never carries the raw token (only expiresAt, user, csrfToken), so capture it from the Set-Cookie: __Host-bc_session=… header with a curl cookie jar (-c). The __Host- prefix marks a cookie only this exact host can set; a local development server over plain http names it bc_session:

curl -X POST https://sandbox.bankconnector.com/api/auth/login \
  -c cookies.txt \
  -H "Content-Type: application/json" \
  -d '{
    "email":     "dev-…@sandbox.bankconnector.com",
    "password":  "a-strong-password"
  }'
# 200 { expiresAt, user, csrfToken }; curl's -c wrote the session token to
# cookies.txt as the Set-Cookie: __Host-bc_session=… value; extract it below

Send that token on every control-plane call:

export BC_SESSION="$(awk '$6 == "__Host-bc_session" { print $7 }' cookies.txt)"
export BC_COMPANY="comp_…"      # companyId from the provision response

Step 2: Create a user

Users are the people who sign in to a company, to view payments, approve them, or administer it. Roles are admin, approver, and/or viewer; at least one is required. Scope the user with companyId in the body:

curl -X POST https://sandbox.bankconnector.com/api/users \
  -H "X-Session-Token: $BC_SESSION" \
  -H "Content-Type: application/json" \
  -d '{
    "companyId":  "'"$BC_COMPANY"'",
    "email":      "ops@contoso.example",
    "name":       "Contoso Ops",
    "password":   "a-strong-password",
    "roles":      ["approver", "viewer"],
    "code":       "123456"
  }'
# 201 { "id": "user_…", "email": "ops@contoso.example", "roles": ["approver","viewer"], ... }

Omit password to send an email invite instead; the user sets their own password via a one-time link (needs email configured on the instance; otherwise create with a password from an admin session).

Creating a user with the admin or approver role is a grant of that role, so it needs your current authenticator code (or a backupCode) when you are enrolled in two-factor or the company requires it; a missing or wrong code answers 422 totp_required. A viewer-only user needs no code.

Creating users works from either an admin session or an API key (into the key's own company only), but a key is capped so it can't escalate: from a key the new user must be a viewer and invite-only (omit password). Creating an admin or approver, setting a password directly, resetting a password, or erasing a user all require an admin session.

Step 3: Issue an API key for the company

Your integration sends payments with an API key, not a session. A key belongs to the company whose admin issues it. The sandbox already gave you one; to issue another (for example one per integration, so each can be revoked on its own):

curl -X POST https://sandbox.bankconnector.com/api/company/api-keys \
  -H "X-Session-Token: $BC_SESSION" \
  -H "Content-Type: application/json" \
  -d '{ "label": "erp-production" }'
# 201 { "id": "apk_…", "key": "key_…", "label": "erp-production", ... }

The raw key is shown in this response only. Then act as the company:

curl -X POST https://sandbox.bankconnector.com/api/journal/payments \
  -H "X-API-Key: $BC_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: contoso-inv-8841" \
  -d '{
    "companyId":   "'"$BC_COMPANY"'",
    "bankKey":     "danske-dk",
    "environment": "test",
    "payment":     { ... }
  }'

companyId must be the key's own company; any other value is 403 forbidden.

More than one company

No credential creates a company from inside another one: a company admin, including the sandbox's dashboardLogin, and every API key belong to one company. To try a second company in the sandbox, provision a second sandbox.

Isolation

Company A (comp_…)   → its own payments, connections, users, API keys
Company B (comp_…)   → isolated from A; A's keys cannot reach it
  • One key, one company. An integration serving several companies holds a separate key for each.
  • Session = control plane, key = data plane. Creating admin users and setting up bank connections needs an admin session; sending and reading payments uses the API key. A leaked integration key can't reshape your company.

Where to go next