Operate / Operator API reference

Operator API reference

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.

Download the spec: openapi.json · openapi.yaml — the full spec covers both tracks.

Connections

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.

Responses

Status	Description
200	Connectivity profiles

Example response (200)

{
  "items": [
    {}
  ]
}

GET/connections

List bank connections for a company

Parameters

Name	In	Required	Description
`platformId` string	query	yes
`companyId` string	query	yes

Responses

Status	Description
200	Connection list
401	Sign in required

Example response (200)

{
  "items": [
    {
      "id": "string",
      "bankKey": "nordea-dk",
      "bankName": "Nordea Danmark",
      "environment": "test",
      "channelType": "sftp",
      "active": false,
      "steps": {
        "introEmailSent": false,
        "pgpGenerated": false,
        "bankPublicKeyAdded": false,
        "serverInfoAdded": false,
        "sftpUserAdded": false,
        "approversAssigned": false,
        "certsIssued": false,
        "bankCertAdded": false,
        "ebicsKeysGenerated": false,
        "ebicsBankKeysFetched": false,
        "wsConfigAdded": false
      },
      "sshPublicKey": "string",
      "pgpPublicKey": "string",
      "approverUserIds": [
        "string"
      ],
      "createdAt": "2026-01-01T00: 00: 00Z"
    }
  ]
}

POST/connections

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

Request body required

Property	Type	Required
`platformId`	string	yes
`companyId`	string	yes
`bankKey`	BankKey	yes
`environment`	enum	no

Example

{
  "platformId": "string",
  "companyId": "string",
  "bankKey": "nordea-dk",
  "environment": "test"
}

Responses

Status	Description
201	Connection created
400	Invalid request
401	Sign in required
403	Admin required

Example response (201)

{
  "connection": {
    "id": "string",
    "bankKey": "nordea-dk",
    "bankName": "Nordea Danmark",
    "environment": "test",
    "channelType": "sftp",
    "active": false,
    "steps": {
      "introEmailSent": false,
      "pgpGenerated": false,
      "bankPublicKeyAdded": false,
      "serverInfoAdded": false,
      "sftpUserAdded": false,
      "approversAssigned": false,
      "certsIssued": false,
      "bankCertAdded": false,
      "ebicsKeysGenerated": false,
      "ebicsBankKeysFetched": false,
      "wsConfigAdded": false
    },
    "sshPublicKey": "string",
    "pgpPublicKey": "string",
    "approverUserIds": [
      "string"
    ],
    "createdAt": "2026-01-01T00: 00: 00Z"
  },
  "readiness": {
    "ready": false,
    "missing": [
      "string"
    ],
    "score": 0
  }
}

GET/connections/{id}

Get a single connection + readiness

Parameters

Name	In	Required
`id` string	path	yes
`platformId` string	query	yes
`companyId` string	query	yes

Responses

Status	Description
200	Connection + readiness
404	Not found

Example response (200)

{
  "connection": {
    "id": "string",
    "bankKey": "nordea-dk",
    "bankName": "Nordea Danmark",
    "environment": "test",
    "channelType": "sftp",
    "active": false,
    "steps": {
      "introEmailSent": false,
      "pgpGenerated": false,
      "bankPublicKeyAdded": false,
      "serverInfoAdded": false,
      "sftpUserAdded": false,
      "approversAssigned": false,
      "certsIssued": false,
      "bankCertAdded": false,
      "ebicsKeysGenerated": false,
      "ebicsBankKeysFetched": false,
      "wsConfigAdded": false
    },
    "sshPublicKey": "string",
    "pgpPublicKey": "string",
    "approverUserIds": [
      "string"
    ],
    "createdAt": "2026-01-01T00: 00: 00Z"
  },
  "readiness": {
    "ready": false,
    "missing": [
      "string"
    ],
    "score": 0
  }
}

PUT/connections/{id}/signing-cert

Pin the bank's published signing certificate

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
`id` string	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.

Example

{
  "platformId": "string",
  "companyId": "string",
  "cert": "string"
}

Responses

Status	Description
200	Pinned
400	Bad certificate or non-WS connection
401	Sign in required
403	Admin required

Example response (200)

{
  "connectionId": "string",
  "certSubject": "string",
  "certExpiry": "2026-01-01T00: 00: 00Z"
}

POST/connections/{id}/activate-danske

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.

Parameters

Name	In	Required	Description
`id` string	path	yes

Request body required

Property	Type	Required	Description
`platformId`	string	yes
`companyId`	string	yes
`userId`	string	yes	Agreement number (User ID) from Danske.
`pin`	string	yes	One-time transfer key from Danske.

Example

{
  "platformId": "string",
  "companyId": "string",
  "userId": "string",
  "pin": "string"
}

Responses

Status	Description
200	Activated
400	Activation failed (wrong PIN, network, etc.)
401	Sign in required
403	Admin required

Example response (200)

{
  "connection": {
    "id": "string",
    "bankKey": "nordea-dk",
    "bankName": "Nordea Danmark",
    "environment": "test",
    "channelType": "sftp",
    "active": false,
    "steps": {
      "introEmailSent": false,
      "pgpGenerated": false,
      "bankPublicKeyAdded": false,
      "serverInfoAdded": false,
      "sftpUserAdded": false,
      "approversAssigned": false,
      "certsIssued": false,
      "bankCertAdded": false,
      "ebicsKeysGenerated": false,
      "ebicsBankKeysFetched": false,
      "wsConfigAdded": false
    },
    "sshPublicKey": "string",
    "pgpPublicKey": "string",
    "approverUserIds": [
      "string"
    ],
    "createdAt": "2026-01-01T00: 00: 00Z"
  },
  "readiness": {
    "ready": false,
    "missing": [
      "string"
    ],
    "score": 0
  }
}

POST/connections/{id}/activate-nordea

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
`id` string	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.
`signerId`	string	yes	Signer ID from the agreement.
`senderId`	string	no
`country`	string	yes
`activationCode`	string	yes	10-digit SMS activation code from Nordea.

Example

{
  "platformId": "string",
  "companyId": "string",
  "holderName": "string",
  "signerId": "string",
  "senderId": "string",
  "country": "string",
  "activationCode": "string"
}

Responses

Status	Description
200	Activated
400	Activation failed
401	Sign in required
403	Admin required

Example response (200)

{
  "connection": {
    "id": "string",
    "bankKey": "nordea-dk",
    "bankName": "Nordea Danmark",
    "environment": "test",
    "channelType": "sftp",
    "active": false,
    "steps": {
      "introEmailSent": false,
      "pgpGenerated": false,
      "bankPublicKeyAdded": false,
      "serverInfoAdded": false,
      "sftpUserAdded": false,
      "approversAssigned": false,
      "certsIssued": false,
      "bankCertAdded": false,
      "ebicsKeysGenerated": false,
      "ebicsBankKeysFetched": false,
      "wsConfigAdded": false
    },
    "sshPublicKey": "string",
    "pgpPublicKey": "string",
    "approverUserIds": [
      "string"
    ],
    "createdAt": "2026-01-01T00: 00: 00Z"
  },
  "readiness": {
    "ready": false,
    "missing": [
      "string"
    ],
    "score": 0
  }
}

POST/connections/{id}/activate-bankconnect

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.

Parameters

Name	In	Required	Description
`id` string	path	yes

Request body required

Property	Type	Required	Description
`platformId`	string	yes
`companyId`	string	yes
`organisationId`	string	yes	Bank registration number.
`functionId`	string	yes	Per-agreement routing code from the bank.
`activationCode`	string	yes	One-time activation code from the bank.

Example

{
  "platformId": "string",
  "companyId": "string",
  "organisationId": "string",
  "functionId": "string",
  "activationCode": "string"
}

Responses

Status	Description
200	Activated
400	Activation failed or bank has no Bank Connect data central
401	Sign in required
403	Admin required
404	Connection not found

Example response (200)

{
  "connection": {
    "id": "string",
    "bankKey": "nordea-dk",
    "bankName": "Nordea Danmark",
    "environment": "test",
    "channelType": "sftp",
    "active": false,
    "steps": {
      "introEmailSent": false,
      "pgpGenerated": false,
      "bankPublicKeyAdded": false,
      "serverInfoAdded": false,
      "sftpUserAdded": false,
      "approversAssigned": false,
      "certsIssued": false,
      "bankCertAdded": false,
      "ebicsKeysGenerated": false,
      "ebicsBankKeysFetched": false,
      "wsConfigAdded": false
    },
    "sshPublicKey": "string",
    "pgpPublicKey": "string",
    "approverUserIds": [
      "string"
    ],
    "createdAt": "2026-01-01T00: 00: 00Z"
  },
  "readiness": {
    "ready": false,
    "missing": [
      "string"
    ],
    "score": 0
  }
}

POST/connections/{id}/generate-pgp

Generate our PGP key pair (SFTP channel)

Parameters

Name	In	Required	Description
`id` string	path	yes

Request body required

Property	Type	Required	Description
`platformId`	string	yes
`companyId`	string	yes

Example

{
  "platformId": "string",
  "companyId": "string"
}

Responses

Status	Description
200	PGP key pair generated
401	Sign in required
403	Admin required

Example response (200)

{
  "connection": {
    "id": "string",
    "bankKey": "nordea-dk",
    "bankName": "Nordea Danmark",
    "environment": "test",
    "channelType": "sftp",
    "active": false,
    "steps": {
      "introEmailSent": false,
      "pgpGenerated": false,
      "bankPublicKeyAdded": false,
      "serverInfoAdded": false,
      "sftpUserAdded": false,
      "approversAssigned": false,
      "certsIssued": false,
      "bankCertAdded": false,
      "ebicsKeysGenerated": false,
      "ebicsBankKeysFetched": false,
      "wsConfigAdded": false
    },
    "sshPublicKey": "string",
    "pgpPublicKey": "string",
    "approverUserIds": [
      "string"
    ],
    "createdAt": "2026-01-01T00: 00: 00Z"
  },
  "readiness": {
    "ready": false,
    "missing": [
      "string"
    ],
    "score": 0
  }
}

POST/connections/{id}/bank-key

Save the bank's PGP public key (SFTP channel)

Parameters

Name	In	Required	Description
`id` string	path	yes

Request body required

Property	Type	Required	Description
`platformId`	string	yes
`companyId`	string	yes
`armoredKey`	string	yes	ASCII-armored PGP public key block.

Example

{
  "platformId": "string",
  "companyId": "string",
  "armoredKey": "string"
}

Responses

Status	Description
200	Bank key saved
401	Sign in required
403	Admin required

Example response (200)

{
  "connection": {
    "id": "string",
    "bankKey": "nordea-dk",
    "bankName": "Nordea Danmark",
    "environment": "test",
    "channelType": "sftp",
    "active": false,
    "steps": {
      "introEmailSent": false,
      "pgpGenerated": false,
      "bankPublicKeyAdded": false,
      "serverInfoAdded": false,
      "sftpUserAdded": false,
      "approversAssigned": false,
      "certsIssued": false,
      "bankCertAdded": false,
      "ebicsKeysGenerated": false,
      "ebicsBankKeysFetched": false,
      "wsConfigAdded": false
    },
    "sshPublicKey": "string",
    "pgpPublicKey": "string",
    "approverUserIds": [
      "string"
    ],
    "createdAt": "2026-01-01T00: 00: 00Z"
  },
  "readiness": {
    "ready": false,
    "missing": [
      "string"
    ],
    "score": 0
  }
}

POST/connections/{id}/server-info

Save SFTP server info (host, port, paths, fingerprint)

Parameters

Name	In	Required	Description
`id` string	path	yes

Request body required

Property	Type	Required
`platformId`	string	yes
`companyId`	string	yes
`host`	string	yes
`port`	integer	no
`uploadPath`	string	no
`downloadPath`	string	no
`hostFingerprint`	string	no

Example

{
  "platformId": "string",
  "companyId": "string",
  "host": "string",
  "port": 22,
  "uploadPath": "string",
  "downloadPath": "string",
  "hostFingerprint": "string"
}

Responses

Status	Description
200	Server info saved
401	Sign in required
403	Admin required

Example response (200)

{
  "connection": {
    "id": "string",
    "bankKey": "nordea-dk",
    "bankName": "Nordea Danmark",
    "environment": "test",
    "channelType": "sftp",
    "active": false,
    "steps": {
      "introEmailSent": false,
      "pgpGenerated": false,
      "bankPublicKeyAdded": false,
      "serverInfoAdded": false,
      "sftpUserAdded": false,
      "approversAssigned": false,
      "certsIssued": false,
      "bankCertAdded": false,
      "ebicsKeysGenerated": false,
      "ebicsBankKeysFetched": false,
      "wsConfigAdded": false
    },
    "sshPublicKey": "string",
    "pgpPublicKey": "string",
    "approverUserIds": [
      "string"
    ],
    "createdAt": "2026-01-01T00: 00: 00Z"
  },
  "readiness": {
    "ready": false,
    "missing": [
      "string"
    ],
    "score": 0
  }
}

POST/connections/{id}/sftp-user

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
`id` string	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.

Example

{
  "platformId": "string",
  "companyId": "string",
  "username": "string"
}

Responses

Status	Description
200	Username set + SSH key generated
401	Sign in required
403	Admin required

Example response (200)

{
  "connection": {
    "id": "string",
    "bankKey": "nordea-dk",
    "bankName": "Nordea Danmark",
    "environment": "test",
    "channelType": "sftp",
    "active": false,
    "steps": {
      "introEmailSent": false,
      "pgpGenerated": false,
      "bankPublicKeyAdded": false,
      "serverInfoAdded": false,
      "sftpUserAdded": false,
      "approversAssigned": false,
      "certsIssued": false,
      "bankCertAdded": false,
      "ebicsKeysGenerated": false,
      "ebicsBankKeysFetched": false,
      "wsConfigAdded": false
    },
    "sshPublicKey": "string",
    "pgpPublicKey": "string",
    "approverUserIds": [
      "string"
    ],
    "createdAt": "2026-01-01T00: 00: 00Z"
  },
  "readiness": {
    "ready": false,
    "missing": [
      "string"
    ],
    "score": 0
  }
}

POST/connections/{id}/approvers

Assign approver users to a connection

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
`id` string	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.

Example

{
  "platformId": "string",
  "companyId": "string",
  "userIds": [
    "string"
  ]
}

Responses

Status	Description
200	Approvers assigned
401	Sign in required
403	Admin required
422	One or more user IDs are not valid approvers in this company

Example response (200)

{
  "connection": {
    "id": "string",
    "bankKey": "nordea-dk",
    "bankName": "Nordea Danmark",
    "environment": "test",
    "channelType": "sftp",
    "active": false,
    "steps": {
      "introEmailSent": false,
      "pgpGenerated": false,
      "bankPublicKeyAdded": false,
      "serverInfoAdded": false,
      "sftpUserAdded": false,
      "approversAssigned": false,
      "certsIssued": false,
      "bankCertAdded": false,
      "ebicsKeysGenerated": false,
      "ebicsBankKeysFetched": false,
      "wsConfigAdded": false
    },
    "sshPublicKey": "string",
    "pgpPublicKey": "string",
    "approverUserIds": [
      "string"
    ],
    "createdAt": "2026-01-01T00: 00: 00Z"
  },
  "readiness": {
    "ready": false,
    "missing": [
      "string"
    ],
    "score": 0
  }
}

POST/connections/{id}/activate

Mark SFTP connection active (after the bank has whitelisted the SSH key)

Parameters

Name	In	Required	Description
`id` string	path	yes

Request body required

Property	Type	Required	Description
`platformId`	string	yes
`companyId`	string	yes

Example

{
  "platformId": "string",
  "companyId": "string"
}

Responses

Status	Description
200	Connection activated
401	Sign in required
403	Admin required

Example response (200)

{
  "connection": {
    "id": "string",
    "bankKey": "nordea-dk",
    "bankName": "Nordea Danmark",
    "environment": "test",
    "channelType": "sftp",
    "active": false,
    "steps": {
      "introEmailSent": false,
      "pgpGenerated": false,
      "bankPublicKeyAdded": false,
      "serverInfoAdded": false,
      "sftpUserAdded": false,
      "approversAssigned": false,
      "certsIssued": false,
      "bankCertAdded": false,
      "ebicsKeysGenerated": false,
      "ebicsBankKeysFetched": false,
      "wsConfigAdded": false
    },
    "sshPublicKey": "string",
    "pgpPublicKey": "string",
    "approverUserIds": [
      "string"
    ],
    "createdAt": "2026-01-01T00: 00: 00Z"
  },
  "readiness": {
    "ready": false,
    "missing": [
      "string"
    ],
    "score": 0
  }
}

POST/connections/{id}/intro-email-sent

Mark intro email as sent (tracks wizard progress)

Parameters

Name	In	Required	Description
`id` string	path	yes

Request body required

Property	Type	Required	Description
`platformId`	string	yes
`companyId`	string	yes

Example

{
  "platformId": "string",
  "companyId": "string"
}

Responses

Status	Description
200	Updated
401	Sign in required
403	Admin required

Example response (200)

{
  "connection": {
    "id": "string",
    "bankKey": "nordea-dk",
    "bankName": "Nordea Danmark",
    "environment": "test",
    "channelType": "sftp",
    "active": false,
    "steps": {
      "introEmailSent": false,
      "pgpGenerated": false,
      "bankPublicKeyAdded": false,
      "serverInfoAdded": false,
      "sftpUserAdded": false,
      "approversAssigned": false,
      "certsIssued": false,
      "bankCertAdded": false,
      "ebicsKeysGenerated": false,
      "ebicsBankKeysFetched": false,
      "wsConfigAdded": false
    },
    "sshPublicKey": "string",
    "pgpPublicKey": "string",
    "approverUserIds": [
      "string"
    ],
    "createdAt": "2026-01-01T00: 00: 00Z"
  },
  "readiness": {
    "ready": false,
    "missing": [
      "string"
    ],
    "score": 0
  }
}

POST/connections/{id}/ws-environment

Toggle a Web Services connection between TEST and PRODUCTION

Requires an already-activated connection (certificates issued); does not re-run PKI.

Parameters

Name	In	Required	Description
`id` string	path	yes

Request body required

Property	Type	Required
`platformId`	string	yes
`companyId`	string	yes
`environment`	enum	yes

Example

{
  "platformId": "string",
  "companyId": "string",
  "environment": "TEST"
}

Responses

Status	Description
200	Environment updated
401	Sign in required
403	Admin required

Example response (200)

{
  "connection": {
    "id": "string",
    "bankKey": "nordea-dk",
    "bankName": "Nordea Danmark",
    "environment": "test",
    "channelType": "sftp",
    "active": false,
    "steps": {
      "introEmailSent": false,
      "pgpGenerated": false,
      "bankPublicKeyAdded": false,
      "serverInfoAdded": false,
      "sftpUserAdded": false,
      "approversAssigned": false,
      "certsIssued": false,
      "bankCertAdded": false,
      "ebicsKeysGenerated": false,
      "ebicsBankKeysFetched": false,
      "wsConfigAdded": false
    },
    "sshPublicKey": "string",
    "pgpPublicKey": "string",
    "approverUserIds": [
      "string"
    ],
    "createdAt": "2026-01-01T00: 00: 00Z"
  },
  "readiness": {
    "ready": false,
    "missing": [
      "string"
    ],
    "score": 0
  }
}

POST/connections/{id}/covered-banks

Set which member banks a shared connection covers

For a shared (group) connection. The store clamps the set to the bank's group and always includes the connection's own bank.

Parameters

Name	In	Required	Description
`id` string	path	yes

Request body required

Property	Type	Required	Description
`platformId`	string	yes
`companyId`	string	yes
`coveredBankKeys`	string[]	yes	Bank keys this connection serves (clamped to the bank's group).

Example

{
  "platformId": "string",
  "companyId": "string",
  "coveredBankKeys": [
    "string"
  ]
}

Responses

Status	Description
200	Covered banks updated
401	Sign in required
403	Admin required

Example response (200)

{
  "connection": {
    "id": "string",
    "bankKey": "nordea-dk",
    "bankName": "Nordea Danmark",
    "environment": "test",
    "channelType": "sftp",
    "active": false,
    "steps": {
      "introEmailSent": false,
      "pgpGenerated": false,
      "bankPublicKeyAdded": false,
      "serverInfoAdded": false,
      "sftpUserAdded": false,
      "approversAssigned": false,
      "certsIssued": false,
      "bankCertAdded": false,
      "ebicsKeysGenerated": false,
      "ebicsBankKeysFetched": false,
      "wsConfigAdded": false
    },
    "sshPublicKey": "string",
    "pgpPublicKey": "string",
    "approverUserIds": [
      "string"
    ],
    "createdAt": "2026-01-01T00: 00: 00Z"
  },
  "readiness": {
    "ready": false,
    "missing": [
      "string"
    ],
    "score": 0
  }
}

POST/connections/{id}/ebics-params

Save EBICS connection parameters (Host ID, Partner ID, User ID, …)

Parameters

Name	In	Required	Description
`id` string	path	yes

Request body required

Property	Type	Required	Description
`platformId`	string	yes
`companyId`	string	yes
`url`	string	yes	EBICS server URL.
`hostId`	string	yes	Bank-assigned Host ID.
`partnerId`	string	yes	Customer ID (PartnerID) from the bank.
`userId`	string	yes	Subscriber ID (UserID) from the bank.
`protocolVersion`	string	no
`signatureVersion`	string	no
`subscriberMode`	enum	no

Example

{
  "platformId": "string",
  "companyId": "string",
  "url": "string",
  "hostId": "string",
  "partnerId": "string",
  "userId": "string",
  "protocolVersion": "H005",
  "signatureVersion": "A006",
  "subscriberMode": "single"
}

Responses

Status	Description
200	EBICS params saved
401	Sign in required
403	Admin required

Example response (200)

{
  "connection": {
    "id": "string",
    "bankKey": "nordea-dk",
    "bankName": "Nordea Danmark",
    "environment": "test",
    "channelType": "sftp",
    "active": false,
    "steps": {
      "introEmailSent": false,
      "pgpGenerated": false,
      "bankPublicKeyAdded": false,
      "serverInfoAdded": false,
      "sftpUserAdded": false,
      "approversAssigned": false,
      "certsIssued": false,
      "bankCertAdded": false,
      "ebicsKeysGenerated": false,
      "ebicsBankKeysFetched": false,
      "wsConfigAdded": false
    },
    "sshPublicKey": "string",
    "pgpPublicKey": "string",
    "approverUserIds": [
      "string"
    ],
    "createdAt": "2026-01-01T00: 00: 00Z"
  },
  "readiness": {
    "ready": false,
    "missing": [
      "string"
    ],
    "score": 0
  }
}

POST/connections/{id}/ebics-generate-keys

Generate EBICS subscriber keys (authentication, encryption, signature)

Parameters

Name	In	Required	Description
`id` string	path	yes

Request body required

Property	Type	Required	Description
`platformId`	string	yes
`companyId`	string	yes

Example

{
  "platformId": "string",
  "companyId": "string"
}

Responses

Status	Description
200	Keys generated
401	Sign in required
403	Admin required

Example response (200)

{
  "connection": {
    "id": "string",
    "bankKey": "nordea-dk",
    "bankName": "Nordea Danmark",
    "environment": "test",
    "channelType": "sftp",
    "active": false,
    "steps": {
      "introEmailSent": false,
      "pgpGenerated": false,
      "bankPublicKeyAdded": false,
      "serverInfoAdded": false,
      "sftpUserAdded": false,
      "approversAssigned": false,
      "certsIssued": false,
      "bankCertAdded": false,
      "ebicsKeysGenerated": false,
      "ebicsBankKeysFetched": false,
      "wsConfigAdded": false
    },
    "sshPublicKey": "string",
    "pgpPublicKey": "string",
    "approverUserIds": [
      "string"
    ],
    "createdAt": "2026-01-01T00: 00: 00Z"
  },
  "readiness": {
    "ready": false,
    "missing": [
      "string"
    ],
    "score": 0
  }
}

GET/connections/{id}/intro-email

Render the bank intro email (draft to send to the bank contact)

Parameters

Name	In	Required
`id` string	path	yes
`platformId` string	query	yes
`companyId` string	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
`id` string	path	yes
`platformId` string	query	yes
`companyId` string	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
`bankKey` BankKey	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
`bankKey` BankKey	path	yes
`platformId` string	query	yes
`companyId` string	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.

Parameters

Name	In	Required	Description
`bankKey` BankKey	path	yes

Request body required

Property	Type	Required
`platformId`	string	no
`companyId`	string	no
`agreementId`	string	no
`chargeBearer`	enum	no
`executionDateOffsetDays`	integer	no
`approvalPolicyId`	string	no
`selected`	boolean	no

Example

{
  "platformId": "string",
  "companyId": "string",
  "agreementId": "string",
  "chargeBearer": "SLEV",
  "executionDateOffsetDays": 0,
  "approvalPolicyId": "string",
  "selected": false
}

Responses

Status	Description
200	Settings saved
401	Sign in required
403	Admin required for payment-affecting fields

GET/bank-settings

List all per-company bank settings in one call

Parameters

Name	In	Required	Description
`platformId` string	query	yes
`companyId` string	query	yes

Responses

Status	Description
200	All saved bank settings for this company

Example response (200)

{
  "settings": [
    {}
  ]
}

Approvals

Maker-checker approval policies + the pending-approval queue (session, Admin/Approver)

GET/approvals/pending

List payments awaiting approval

Parameters

Name	In	Required	Description
`companyId` string	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.

Parameters

Name	In	Required	Description
`id` string	path	yes

Request body required

Property	Type	Required	Description
`platformId`	string	yes
`companyId`	string	yes
`reason`	string	no
`code`	string	no	2FA TOTP code (if step-up required).
`backupCode`	string	no

Example

{
  "platformId": "string",
  "companyId": "string",
  "reason": "string",
  "code": "string",
  "backupCode": "string"
}

Responses

Status	Description
200	Approval recorded (and payment dispatched if fully approved)
401	Sign in required
403	Maker cannot approve own payment / not an approver

POST/approvals/{id}/reject

Reject a pending payment

Parameters

Name	In	Required	Description
`id` string	path	yes

Request body required

Property	Type	Required
`platformId`	string	yes
`companyId`	string	yes
`reason`	string	no

Example

{
  "platformId": "string",
  "companyId": "string",
  "reason": "string"
}

Responses

Status	Description
200	Rejection recorded
401	Sign in required

GET/approvals/policies

List approval policies for a company

Parameters

Name	In	Required	Description
`companyId` string	query	yes

Responses

Status	Description
200	Policies
401	Sign in required

Example response (200)

{
  "policies": [
    {}
  ]
}

POST/approvals/policies

Create an approval policy (Admin)

Defines required approver count + amount thresholds. Admin only.

Request body required

Property	Type	Required
`platformId`	string	yes
`companyId`	string	yes
`name`	string	yes
`requiredApprovals`	integer	no
`thresholdAmount`	string	no
`currency`	string	no

Example

{
  "platformId": "string",
  "companyId": "string",
  "name": "string",
  "requiredApprovals": 0,
  "thresholdAmount": "string",
  "currency": "string"
}

Responses

Status	Description
201	Policy created
401	Sign in required
403	Admin required

POST/approvals/policies/{id}

Edit a DRAFT approval policy (Admin)

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.

Parameters

Name	In	Required	Description
`id` string	path	yes

Request body required

Property	Type	Required
`platformId`	string	yes
`companyId`	string	yes
`name`	string	no
`requiredApprovals`	integer	no
`thresholdAmount`	string	no
`currency`	string	no

Example

{
  "platformId": "string",
  "companyId": "string",
  "name": "string",
  "requiredApprovals": 0,
  "thresholdAmount": "string",
  "currency": "string"
}

Responses

Status	Description
200	Updated draft policy
401	Sign in required
403	Admin required
409	Version is not a draft / conflict

Example response (200)

{
  "policy": {}
}

POST/approvals/policies/{id}/lock

Activate (lock) a draft approval policy (Admin)

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
`id` string	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
`id` string	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
`status` enum	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).

Parameters

Name	In	Required	Description
`changeId` string	path	yes
`action` enum	path	yes

Request body required

Property	Type	Required	Description
`platformId`	string	yes
`companyId`	string	yes

Example

{
  "platformId": "string",
  "companyId": "string"
}

Responses

Status	Description
200	Change updated
401	Sign in required
403	Admin required
409	Same-admin co-sign / conflict

Example response (200)

{
  "change": {},
  "policy": {},
  "supersededId": "string",
  "affectedBanks": [
    "string"
  ]
}

Auth

POST/auth/login

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

Request body required

Property	Type	Required
`subdomain`	string	yes
`email`	string	yes
`password`	string	yes

Example

{
  "subdomain": "demo",
  "email": "string",
  "password": "string"
}

Responses

Status	Description
200	Logged in (token) OR a 2FA step-up challenge
401	Invalid credentials

Example response (200)

{
  "token": "string",
  "twoFactorRequired": false
}

Code samples

curl -X POST https://your-host/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"subdomain":"demo","email":"you@acme.com","password":"…"}'

const res = await fetch("https://your-host/auth/login", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
  },
  body: JSON.stringify({"subdomain":"demo","email":"you@acme.com","password":"…"}),
});
const data = await res.json();

import requests

resp = requests.request(
  "POST", "https://your-host/auth/login",
  json={"subdomain":"demo","email":"you@acme.com","password":"…"},
)
resp.raise_for_status()
data = resp.json()

POST/2fa/setup

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.

Responses

Status	Description
200	Pending secret + otpauth URI
401	Sign in first

Example response (200)

{
  "secret": "string",
  "otpauthUri": "string",
  "issuer": "string"
}

POST/2fa/confirm

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

Responses

Status	Description
200	Platform branding

Example response (200)

{
  "platformId": "string",
  "displayName": "string",
  "subdomain": "string",
  "logoUrl": "string"
}

POST/auth/2fa

Complete a 2FA login step-up (PUBLIC)

PUBLIC. Submits the TOTP (or backup) code against the challenge from POST /auth/login to obtain the session.

Request body required

Property	Type	Required	Description
`challenge`	string	yes	The challenge id from /auth/login.
`code`	string	yes
`backupCode`	string	no

Example

{
  "challenge": "string",
  "code": "string",
  "backupCode": "string"
}

Responses

Status	Description
200	Session granted
401	Invalid code

Example response (200)

{
  "token": "string"
}

User Management

Create, invite, and manage users within a company. Also covers workspace (platform) admin accounts.

GET/platforms/{platformId}/admins

List workspace admins for a platform

Returns all workspace (platform) admin accounts. Workspace-admin session required.

Parameters

Name	In	Required	Description
`platformId` string	path	yes

Responses

Status	Description
200	Workspace admins
403	Not a workspace admin

Example response (200)

{
  "items": [
    {
      "id": "string",
      "email": "string",
      "name": "string"
    }
  ],
  "nextCursor": "string"
}

POST/platforms/{platformId}/admins

Create a workspace admin

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.

Request body required

Property	Type	Required	Description
`email`	string	yes
`name`	string	yes
`password`	string	yes	Initial password. Minimum 8 characters.

Example

{
  "email": "admin@acme.com",
  "name": "Alice Admin",
  "password": "string"
}

Responses

Status	Description
201	Admin created
400	Invalid request or duplicate email
403	Not a workspace admin (when auth is enabled)

Example response (201)

{
  "id": "string",
  "email": "string",
  "name": "string"
}

GET/users

List users in a company

Returns all users in the company (name, email, roles, status). Readable by any authenticated company member.

Parameters

Name	In	Required	Description
`platformId` string	query	yes
`companyId` string	query	yes

Responses

Status	Description
200	Company users
401	Sign in required

Example response (200)

{
  "users": [
    {
      "id": "string",
      "email": "string",
      "name": "string",
      "roles": [
        "admin"
      ],
      "status": "active"
    }
  ]
}

POST/users

Create or invite a company user

Company admin only. Two modes:

With password: creates the user immediately (active). Use for programmatic provisioning.
Without password: sends an invite email. The user receives a link to /auth/set-password where they set their own password.

The user must be given at least one role (admin, approver, and/or viewer). Users who will be assigned as payment approvers need the approver role.

Request body required

Property	Type	Required	Description
`platformId`	string	yes
`companyId`	string	yes
`email`	string	yes
`name`	string	yes
`roles`	enum[]	yes
`password`	string	no	If omitted, an invite email is sent and the user sets their own password.

Example

{
  "platformId": "string",
  "companyId": "string",
  "email": "approver@acme.com",
  "name": "Bob Approver",
  "roles": [
    "approver"
  ],
  "password": "string"
}

Responses

Status	Description
201	User created or invite sent
400	Invalid request, duplicate email, or no valid roles
403	Company admin required

Example response (201)

{
  "id": "string",
  "email": "string",
  "name": "string",
  "roles": [
    "string"
  ],
  "invited": false
}

POST/auth/set-password

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.

Request body required

Property	Type	Required	Description
`query`	string	yes	BIC code or bank name.
`email`	string	no

Example

{
  "query": "string",
  "email": "string"
}

Responses

Status	Description
201	Request recorded
400	Empty query

Example response (201)

{
  "ok": false,
  "request": {
    "id": "string",
    "query": "string",
    "createdAt": "2026-01-01T00: 00: 00Z"
  }
}

Workspace Admin

GET/platforms/{platformId}/companies

List the companies under a platform

Workspace (platform) admin only. The company list a workspace admin manages: drives the GUI company list + company-switcher (POST /auth/company-context).

Parameters

Name	In	Required	Description
`platformId` string	path	yes

Responses

Status	Description
200	Companies
403	Not a workspace admin

Example response (200)

{
  "items": [
    {
      "id": "string",
      "name": "string",
      "createdAt": "2026-01-01T00: 00: 00Z"
    }
  ],
  "nextCursor": "string"
}

POST/platforms/{platformId}/companies

Create a company under a platform

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.

Parameters

Name	In	Required	Description
`platformId` string	path	yes

Request body required

Property	Type	Required	Description
`name`	string	yes	Display name for the company.

Example

{
  "name": "Acme Payments Ltd"
}

Responses

Status	Description
201	Company created
400	Invalid request
403	Not a workspace admin

Example response (201)

{
  "company": {
    "id": "comp_…",
    "name": "string",
    "createdAt": "2026-01-01T00: 00: 00Z"
  }
}

POST/auth/company-context

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.

Parameters

Name	In	Required	Description
`platformId` string	path	yes

Responses

Status	Description
200	API keys (no secret)
403	Not a workspace admin

Example response (200)

{
  "items": [
    {
      "id": "string",
      "label": "string",
      "createdAt": "2026-01-01T00: 00: 00Z",
      "lastUsedAt": "2026-01-01T00: 00: 00Z"
    }
  ],
  "nextCursor": "string"
}

POST/platforms/{platformId}/api-keys

Create an API key: the raw key is returned ONCE

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.

Parameters

Name	In	Required	Description
`platformId` string	path	yes

Request body required

Property	Type	Required	Description
`label`	string	yes	Human name, e.g. "Production ERP".

Example

{
  "label": "string"
}

Responses

Status	Description
201	Key created: raw key shown once
400	Invalid request
403	Not a workspace admin

Example response (201)

{
  "id": "string",
  "key": "string",
  "label": "string",
  "createdAt": "2026-01-01T00: 00: 00Z"
}

DELETE/platforms/{platformId}/api-keys/{keyId}

Revoke an API key

Workspace (platform) admin only. Soft-revokes the key (it stays for audit but stops authenticating immediately).

Parameters

Name	In	Required	Description
`platformId` string	path	yes
`keyId` string	path	yes

Responses

Status	Description
200	Revoked
403	Not a workspace admin
404	Unknown key for this platform