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.

POST /api/sandbox/provision creates no sign-in. Sign up at /signup with an email you verify: the signup creates a sandbox company of its own, with you as its admin, and you choose your password when you verify. 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":     "you@example.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_…"      # your company's id, from the login response's user

Step 2: Invite 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",
    "roles":      ["approver", "viewer"],
    "code":       "123456"
  }'
# 201 { "id": "user_…", "email": "ops@contoso.example", "roles": ["approver","viewer"], "invited": true, ... }

The user gets an email invite and sets their own password via a one-time link; nobody else ever chooses it. The instance needs email configured to send it.

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.

Inviting 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. Inviting an admin or approver, resetting a password, or erasing a user all require an admin session. In a sandbox company that POST /api/sandbox/provision created, a key invites nobody (403 sandbox_signup_required); invite from the session of a sandbox you signed up for.

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