The setup & administration endpoints an operator or workspace admin uses to stand a tenant up and keep it running — bank connections and channel activation, approvals, users, workspace/company admin, and session sign-in. These are session-authenticated (an X-API-Key gets 403); the day-to-day integration surface is in the API reference.
Bank connection setup, channel activation, and EBICS onboarding (session-authenticated, Admin only)
GET/connectivity/profiles
List connectivity profiles (channel info per bank)
Read-only metadata: which channel each bank uses (sftp / danske-ws / nordea-ca / bankconnect / ebics), its pre-known server/endpoint details, and SFTP wizard config. No auth required.
Create (or find existing) bank connection: starts the setup wizard
Creates a bank connection for the given company, or returns the existing one if already set up. Platform-admin note: if you are authenticated as a workspace (platform) admin, you must enter a company context first via POST /auth/company-context before calling this endpoint. Without it you will receive: "select a company context first."
Stores the bank's PUBLISHED X.509 signing certificate (PEM or base64-DER) on the connection so inbound Web Services signatures are verified against it (fail-closed on any mismatch). Admin only. Validates the cert parses (400 on bad input). Returns the cert subject + expiry so the operator can confirm they pinned the right cert; the raw PEM is never returned. GET /connections/{id} then surfaces signingCertSubject / signingCertExpiry.
Parameters
Name
In
Required
Description
idstring
path
yes
Request body required
Property
Type
Required
Description
platformId
string
yes
companyId
string
yes
cert
string
yes
The bank's published signing certificate — PEM (-----BEGIN CERTIFICATE-----) or base64-DER.
Activate Danske EDI Web Services (automated cert enrolment)
Calls the Danske bxd.fi activation endpoint with the one-time PIN, self-issues the signing + encryption certificates, and marks the connection active. Admin only.
Activate Nordea Corporate Access (HMAC cert enrolment via SMS code)
Generates a Nordea-format signing CSR, sends the HMAC-signed enrolment request to Nordea's Corporate Access endpoint using the SMS activation code, and stores the issued certificate. Admin only.
Parameters
Name
In
Required
Description
idstring
path
yes
Request body required
Property
Type
Required
Description
platformId
string
yes
companyId
string
yes
holderName
string
yes
Certificate-holder name (CN) as printed in the Nordea agreement.
Activate Bank Connect (DK gateway: automated cert enrolment)
Enrols the signing certificate with the Bank Connect data central (BD/BEC/SDC), stores the issued certificate and bank public key, and marks the connection active. Data central and country are pre-filled from the bank profile. Admin only.
Issues fresh signing + encryption keypairs/CSRs to Danske's PKI via RenewCertificate — the request is enveloped-signed with the current signing certificate and XML-encrypted to the bank certificate (PKI WS spec §7) — and commits the new keys + certificates atomically on success. Run before the 2-year certificate expiry (the cert-expiring alerts fire at 30/14/7 days). A failed renewal leaves the current credentials untouched. Admin only.
Parameters
Name
In
Required
Description
idstring
path
yes
Request body required
Property
Type
Required
Description
platformId
string
yes
companyId
string
yes
Example
{
"platformId": "string",
"companyId": "string"
}
Responses
Status
Description
200
Renewed
400
Renewal failed (current credentials left untouched)
Renew the Nordea Corporate Access signing certificate
Issues a fresh keypair + CSR (same subject as the current certificate) to Nordea's Certificate Service — the CertApplicationRequest is signed with the current certificate in place of the HMAC (Certificate Management §3.1.2), so no new SMS activation code is needed while the current certificate is valid — and commits the new key + certificate atomically on success. Run before the 2-year expiry (alerts at 30/14/7 days). A failed renewal leaves the current credentials untouched. Admin only.
Parameters
Name
In
Required
Description
idstring
path
yes
Request body required
Property
Type
Required
Description
platformId
string
yes
companyId
string
yes
Example
{
"platformId": "string",
"companyId": "string"
}
Responses
Status
Description
200
Renewed
400
Renewal failed (current credentials left untouched)
Issues a fresh keypair + CSR (CN=functionId) to the Bank Connect data central via renewCustomerCertificate, signed with the current certificate, and commits the new key + certificate atomically on success. Run before the 3-year certificate expiry (the cert-expiring alerts fire at 30/14/7 days); the bank revokes the previous certificate 48 hours after a successful renewal. Admin only.
Parameters
Name
In
Required
Description
idstring
path
yes
Request body required
Property
Type
Required
Description
platformId
string
yes
companyId
string
yes
Example
{
"platformId": "string",
"companyId": "string"
}
Responses
Status
Description
200
Renewed
400
Renewal failed (current credentials left untouched)
Set SFTP username and generate SSH key pair (single combined call)
Sets the SFTP username AND generates the SSH key pair in one call: you cannot pre-generate the key before you have the username. The username must be obtained from the bank first; only then can you call this endpoint. The response includes the connection + readiness state, from which you can retrieve the generated SSH public key to send to the bank for whitelisting.
Parameters
Name
In
Required
Description
idstring
path
yes
Request body required
Property
Type
Required
Description
platformId
string
yes
companyId
string
yes
username
string
yes
SFTP username assigned by the bank. Required: the SSH key generation and username registration are a single atomic operation.
Assigns which users may approve payments on this connection. Approvers and approval policy are separate: the policy (under POST /approvals/policies) defines the rule (how many approvers, any amount thresholds); this endpoint assigns the eligible users per connection. Both must be in place for a connection to reach go-live. Note: users must first exist in the company: create them with POST /users before assigning them as approvers.
Parameters
Name
In
Required
Description
idstring
path
yes
Request body required
Property
Type
Required
Description
platformId
string
yes
companyId
string
yes
userIds
string[]
yes
User IDs of company members with the Approver role. Must already exist in the company.
Render the bank intro email (draft to send to the bank contact)
Parameters
Name
In
Required
Description
idstring
path
yes
platformIdstring
query
yes
companyIdstring
query
yes
Responses
Status
Description
200
Rendered email (subject + body)
404
Not found
GET/connections/{id}/ebics-letter
Download the EBICS initialisation letter (PDF, base64-encoded)
Returns the signed INI/HIA initialisation letter as a base64-encoded PDF. Print, sign, and send to the bank to complete EBICS subscriber activation.
Parameters
Name
In
Required
Description
idstring
path
yes
platformIdstring
query
yes
companyIdstring
query
yes
Responses
Status
Description
200
PDF as base64
404
Not found or keys not yet generated
Example response (200)
{
"pdfBase64": "string",
"filename": "string"
}
GET/banks/{bankKey}/setup-info
Per-bank setup descriptor for the wizard UI
Returns the channel kind, requirements text, field definitions, pre-known server/endpoint details, and SFTP wizard screens for a bank. Used by the setup wizard to render the correct flow.
Parameters
Name
In
Required
Description
bankKeyBankKey
path
yes
Responses
Status
Description
200
Setup descriptor
404
Unknown bank
GET/banks/{bankKey}/settings
Get per-company settings for a specific bank
Parameters
Name
In
Required
Description
bankKeyBankKey
path
yes
platformIdstring
query
yes
companyIdstring
query
yes
Responses
Status
Description
200
Bank settings (null if none saved)
POST/banks/{bankKey}/settings
Update per-company settings for a specific bank
Payment-affecting fields (agreementId, chargeBearer, executionDateOffsetDays, approvalPolicyId) require Admin. The selected pin is open to any member.
Maker-checker approval policies + the pending-approval queue (session, Admin/Approver)
GET/approvals/pending
List payments awaiting approval
Parameters
Name
In
Required
Description
companyIdstring
query
yes
Responses
Status
Description
200
Pending approval requests
401
Sign in required
Example response (200)
{
"requests": [
{}
]
}
POST/approvals/{id}/approve
Approve a pending payment (maker ≠ checker enforced)
An approver other than the maker approves the request; once the policy's required approvals are met the payment proceeds to delivery. May require a 2FA code/backup code if step-up is configured.
Edit a policy's name / required approver count / thresholds. Works only on a DRAFT version — an Active version is immutable (409); change it via /approvals/policies/{id}/propose then co-sign.
Locks a DRAFT version → Active and immutable. Runs the quorum check (a dual policy needs ≥2 named approvers); fails 409 if it can't be met. An Active version is changed only via propose + co-sign.
Parameters
Name
In
Required
Description
idstring
path
yes
Request body required
Property
Type
Required
Description
platformId
string
yes
companyId
string
yes
Example
{
"platformId": "string",
"companyId": "string"
}
Responses
Status
Description
200
Policy activated
401
Sign in required
403
Admin required
409
Quorum not met / conflict
Example response (200)
{
"policy": {}
}
POST/approvals/policies/{id}/propose
Propose a change to an Active policy (Admin)
Clones the Active version to an editable draft v(n+1). Edit the draft (POST /approvals/policies/{draftId}), then submit it for activation via POST /approvals/changes/{changeId}/submit and have a second Admin co-sign via POST /approvals/changes/{changeId}/cosign. The old version is retained forever once superseded.
Parameters
Name
In
Required
Description
idstring
path
yes
Request body required
Property
Type
Required
Description
platformId
string
yes
companyId
string
yes
Example
{
"platformId": "string",
"companyId": "string"
}
Responses
Status
Description
201
Draft version created
401
Sign in required
403
Admin required
409
Base not Active / change already in progress
Example response (201)
{
"policy": {}
}
GET/approvals/changes
List approval-policy change requests (Admin)
The dual-co-sign change requests for the company. ?status=pending (default) | activated | cancelled.
Parameters
Name
In
Required
Description
statusenum
query
no
Responses
Status
Description
200
Change requests
401
Sign in required
403
Admin required
Example response (200)
{
"changes": [
{}
]
}
POST/approvals/changes/{changeId}/{action}
Submit / co-sign / cancel a policy change (Admin)
action=submit — the proposer submits the draft for activation (counts as the FIRST of 2 co-signs). action=cosign — a SECOND, distinct Admin co-signs: the new version goes Active, the base is Superseded, and attached banks re-point to the new version. action=cancel — any Admin cancels a pending change (the draft is discarded; the base stays Active). A 2nd co-sign by the same Admin is refused (409).
Login, session, and 2FA. Login + demo are PUBLIC; the rest need a session.
POST/auth/login
Log in (PUBLIC): returns a session token + sets the session cookie
PUBLIC. Exchanges subdomain + email + password for a signed session. If 2FA is enabled, returns a step-up challenge instead (complete it at POST /auth/2fa).
Begin 2FA enrollment (signed-in user) — returns a TOTP secret + otpauth URI
Generates a NOT-yet-active TOTP secret for the signed-in user and returns its otpauth:// URI (render as a QR). Activate it with POST /2fa/confirm. Session-only.
Confirm 2FA enrollment with a TOTP code — returns one-time backup codes
Verifies a code against the pending secret and activates 2FA. The backup codes are returned EXACTLY ONCE — surface + warn. Session-only; throttled per user.
Request body required
Property
Type
Required
Description
code
string
yes
6-digit TOTP code
Example
{
"code": "string"
}
Responses
Status
Description
200
Enabled + one-time backup codes
400
Setup not started
409
Already enabled
422
Code didn't match
429
Too many attempts (Retry-After)
Example response (200)
{
"enabled": false,
"backupCodes": [
"string"
]
}
POST/2fa/disable
Disable 2FA (requires a fresh code; blocked when the company forces 2FA)
Turns off the signed-in user's 2FA after verifying a fresh TOTP or backup code; refused (403) when the company requires 2FA. Revokes the user's OTHER sessions. Session-only; throttled.
Request body required
Property
Type
Required
Description
code
string
no
backupCode
string
no
Example
{
"code": "string",
"backupCode": "string"
}
Responses
Status
Description
200
Disabled
403
Company requires 2FA
409
Not enabled
422
A valid code is required
429
Too many attempts (Retry-After)
Example response (200)
{
"enabled": false
}
POST/company/require-2fa
Admin: set the company-wide 2FA requirement
Admin-only. When enabled, every user in the company must enroll in 2FA. Distinct from the per-user enabled state — the response field is require2fa (company policy).
Request body required
Property
Type
Required
Description
enabled
boolean
yes
Example
{
"enabled": false
}
Responses
Status
Description
200
Updated company policy
403
Admin role required
Example response (200)
{
"require2fa": false
}
GET/auth/me
Current principal (who am I)
Responses
Status
Description
200
The signed-in user + roles + company
401
Not signed in
POST/auth/logout
Log out (invalidates the session)
Responses
Status
Description
200
Logged out
GET/auth/platform-info
Public platform branding for the login page
Returns the branding for the platform resolved from the request's subdomain (no auth — called before login). On a known subdomain: the platform's display name + subdomain. Otherwise the generic BankConnector branding. logoUrl is reserved for a later phase (null for now).
Creates a new workspace (platform) admin account with a password. Bootstrap note: when the server is running in open/unauthenticated mode (no BANKCONNECTOR_API_KEYS set, e.g. first-time setup), this endpoint is accessible without a session: use it to create the very first admin. Once auth is enabled, an existing workspace-admin session is required.
Complete an invite: set password from email token (PUBLIC)
PUBLIC. Called when an invited user clicks their invite link. Validates the one-time token and sets the user's password. Any existing sessions for the user are revoked. The token comes from the invite email.
Request body required
Property
Type
Required
Description
token
string
yes
The one-time invite token from the email link.
password
string
yes
The user's chosen password.
Example
{
"token": "string",
"password": "string"
}
Responses
Status
Description
200
Password set
400
Invalid or expired token
429
Too many attempts: IP rate-limited
Example response (200)
{
"ok": false,
"email": "string"
}
Platform
Tenant dashboard + per-bank test payments
GET/bank-requests
List all bank requests (Admin only)
Responses
Status
Description
200
All requests
401
Sign in required
403
Admin required
Example response (200)
{
"items": [
{}
]
}
POST/bank-requests
Request a bank we don't support yet
Any signed-in user (or anonymous) can submit a BIC or bank name. The request is queued for the development team.
Workspace (platform) admin only. The company list a workspace admin manages: drives the GUI company list + company-switcher (POST /auth/company-context).
Workspace (platform) admin only. Creates a new company (tenant) under the platform. Requires a session (workspace-admin login): not an API key. After creation, use POST /auth/company-context to enter the company and make company-scoped calls.
Enter a company context (platform admin acts AS a company)
Workspace (platform) admin only. Sets the session's active company so the admin acts as an ADMIN of that company. The company must belong to the admin's platform. Cleared with DELETE.
Request body required
Property
Type
Required
Description
companyId
string
yes
Example
{
"companyId": "string"
}
Responses
Status
Description
200
Context set
403
Not a workspace admin
404
Unknown company in your platform
Example response (200)
{
"ok": false
}
DELETE/auth/company-context
Exit the company context (back to pure platform-admin scope)
Responses
Status
Description
200
Context cleared
403
Not a workspace admin
Example response (200)
{
"ok": false
}
GET/platforms/{platformId}/api-keys
List a platform's API keys (metadata only: never the secret)
Workspace (platform) admin only. Returns active (non-revoked) keys with id, label, createdAt and lastUsedAt. The raw key is NEVER returned here: it is shown once, at creation.
Workspace (platform) admin only. Mints a new platform API key; the raw key value appears ONLY in this 201 response and is never stored or retrievable again. Store it securely.