ISECure WS Channel API API Reference

The API provides secure file exchange with all common banks in Finland via SEPA WebServices channel on the API side towards the banks, including certificate enrollment (PKI) with automatic renewals.

The API specification in OpenAPI v2 format can be found on GitHub isecurefi/wsapi-v2. Command line CLI and beefed-up PHP SDK are also available on GitHub isecurefi/wscli-php.

% export SESSION=~/.wscli/settings.yaml
% wscli session login -c $SESSION
% export APIKEY=`yq -r .settings.apikey $SESSION`
% export IDTOKEN=`yq -r .settings.idtoken $SESSION`
%
% curl -H Authorization:$IDTOKEN \ 
       -H x-api-key:$APIKEY \ 
       https://ws-api.isecure.fi/v2/files/danskebank

API provides simple role based access control (RBAC) and user account management, password recovery, and SMS based Multi Factor Authentication based on AWS Cognito Your User Pool managed service.

NOTE: The API endpoint for production is the same as for test, but without test. in the URL. Production and test APIs are deployd on separate AWS accounts.

NOTE: The API is run on AWS API Gateway and with AWS Lambda backend. When Lambda functions are cold, there is a small delay in response time. Additionally, banks have considerable delays in their processings, especially with certificate enrollments.

Service enrollment

Every integrator (partner) has own API Key and every user account belongs to one integrator. API Key is bound with service subscription. In other words, enrolling fresh API Key requires service agreement before file transfers are allowed on production accounts.

If user registers with 0 API Key (i.e. no API Key) she gets a fresh API Key and becomes the API Key owner. The API Key owner account can list all users under the same API Key, see the Integrator API. Integrators (partners) registers their own API Key owner accounts and use it to register their client accounts.

NOTE: API call rate limits are set and tracked per API Key by AWS API Gateway.

Account management

A user (email address) can register either admin or data or both roles. The role in the API is referred to as mode. Both modes have separate passwords and provide differing capabilities for the user.

Login always requires account mode parameter in addition to user's email address and password. Admin mode login always requires an additional SMS one-time-password (MFA), whilst with data mode password is enough (suitable for automation). Admin mode is used to configure the account (e.g. adding PGP keys and sharing certs) and data mode to exchange files. Listing files is allowed on both modes.

NOTE: Integrator (partner) registers her customers by using her API Key from the API Key owner account.

Bank certificate enrollment

The SEPA WebServices connection to the bank requires enrolling PKI certificate with the bank. The Admin mode can enroll certificates for different banks, but only one certificate per bank. The corresponding private key is stored encrypted with AWS KMS service.

Bank certificate sharing

It is possible to share the same bank certificate with multiple accounts. Certificate sharing between accounts can be configured when accounts have the same API Key. Account that holds the certificate can share/unshare it with another account ( admin mode operation). Note that only the account that has the certificate can PGP export the certificate and corresponding private key. This allows creating e.g. one admin mode only account and multiple data mode only accounts, where the admin account shares its certificates with other data accounts.

An account can never have multiple certificates per bank, be it shared or account's enrolled certificate. This is because the API requires identification of the bank, but not the certificate and private key pair.

Access security

Access is secured with TLS on Amazon Web Services (AWS) API Gateway. Inside TLS, secure sessions are established by using email address as username and by RSA encrypting password along with dynamic username specific parameters fetched from the API with InitRegister or InitLogin API commands (challenge response).

Successful login provides a session token (AWS Cognito User Pool). Authorization happens with the session token (Authorization) and API Key (x-api-key) headers.

Administrative actions require SMS based MFA authentication (see admin mode). User account management is handled with AWS Cognito User Pools and each user (email) has separate admin and/or data mode (role) accounts sharing the same API account data.

CHANGELOG

2.6.0 :: 2021-06-14

  • Added token revocation for logout (AWS SDK based new capability), no changes to the API itself.

2.5.0 :: 2020-04-19

  • Removed OPTIONS
  • Fixed Login response.
API Endpoint
https://ws-api.test.isecure.fi/v2
Terms of Service: https://www.isecure.fi/ws-api-terms
Contact: dan.forsberg@isecure.fi
Schemes: https
Version: v2.6.0

Authentication

Authorizer

Successful login provides IdToken that must be provided in the Authorization header

in
header
name
Authorization
type
apiKey

X-Api-Key

Integrator specific API Key. For all integrator customers, the API key must be the same.

in
header
name
x-api-key
type
apiKey

Account

Account

InitRegister

GET /account/{Email}/{Mode}

Before register (or login), client must fetch challenge from the API. Then on register (or login), the challenge must be passed along to the API (as response to the challenge). The challenge is always fresh for some period of time and the API validates it when passed with register (or login). The challenge has form of base64-string|timestamp|uuid. For example:

ezwXceQ63fV9oWTSJBAE2Zq1Cw5tBIJe+7+Rl8jrgbk=|1475429754114|4017bda8-0a15-4154-a8b7-88069b05cb4e

NOTE: The call must contain the same email as used for registration itself.

Email: string
in path

Email address as the account username, e.g. dan.forsberg@isecure.fi

Mode: string admin, data
in path

Administer account with admin mode, exchange files with data mode

200 OK
InitRegisterResp

Operation succesfully processed. See response.

400 Bad Request
ErrorResponse

Request validation error

500 Internal Server Error
ErrorResponse

Unexpected error occurred

Response Content-Types: application/json
Response Example (200 OK) 
{
  "Challenge": "9Ty4zrnJGqNH0i1+I0OTKHjTs03Ymd4tBH70FTiYNhA=|1494962070679|2646b71b-9b51-4d11-bf5e-cca5617bcfde",
  "ResponseCode": "..",
  "ResponseText": ".."
}
Response Example (400 Bad Request) 
{
  "RequestId": "string",
  "ResponseCode": "string",
  "ResponseText": "string"
}
Response Example (500 Internal Server Error) 
{
  "RequestId": "string",
  "ResponseCode": "string",
  "ResponseText": "string"
}
Account

VerifyEmail

POST /account/{Email}/{Mode}

Provide Code received to Email address for email address verification. Provide also AccessToken received during login.

NOTE: Phone and EMail verification can be bypassed per API key on request to dan.forsberg@isecure.fi . E.g. if integrator verifies EMail and Phone beforehand.

VerifyEmailReq

Account parameters

Email: string
in path

Email address as the account username, e.g. dan.forsberg@isecure.fi

Mode: string admin, data
in path

Administer account with admin mode, exchange files with data mode

Request Content-Types: application/json
Request Example
{
  "AccessToken": "eyJraWQiO...CzzcdcdAdEzKIcJPR7Fda0A",
  "Code": "123456"
}
200 OK
Response

Operation succesfully processed. See response.

400 Bad Request
ErrorResponse

Request validation error

500 Internal Server Error
ErrorResponse

Unexpected error occurred

Response Content-Types: application/json
Response Example (200 OK) 
{
  "ResponseCode": "string",
  "ResponseText": "string"
}
Response Example (400 Bad Request) 
{
  "RequestId": "string",
  "ResponseCode": "string",
  "ResponseText": "string"
}
Response Example (500 Internal Server Error) 
{
  "RequestId": "string",
  "ResponseCode": "string",
  "ResponseText": "string"
}
Account

Register

PUT /account/{Email}/{Mode}

You need to register both admin and data accounts with the same email address. Both accounts share the same data, but are used for different purposes. Admin account must be registered first, then data account.

Admin account is used to configure setup with Certs and Pgp operations, while the data account is used with Files operations only. Both accounts use Account and Session operations.

Admin account always requires SMS MFA during login, whilst data account does not. Generally, the data account is considered read-noly when no PGP keys are configured, since PGP Keys are used to verify file upload signatures and are thus required to successfully upload files with Files UploadFile operation.

Registrations are independent for both accounts, admin and data and both require phone number and email verifications.

email is the login username for both accounts and mode defines the selected "mode" for the login, i.e. admin or data.

Before registration client must fetch challenge from API (see Account InitRegister operation) and pass it back within the ChResp parameter.

The following parameters name, phone, and company are required and must be valid (phone, email) as they need to be confirmed before registration becomes successful and login possible.

Client must RSA encrypt (OAEP padding) the password and the challenge timestamp as string in the form password||timestamp, base64 encode it and provide the resulting string as Encrypted parameter. The RSA encryption can be done e.g. for illustration purposes within command line with openssl rsautl:

echo -n Toddler_..123456789012345\|\|1475175151231 |
    openssl rsautl -oaep -encrypt -pubin -inkey test.pem |
    base64

The test API's RSA public key is as follows:

% cat test.pem
-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAkuSaoSZztGAIGDTY7Rff
psBHJJT1k207UodOJbYFhHAq0lWJnvMPLl5Q1DUUZdTGtTdL8Dsaj/Bo2+gSykMM
R5QiKewvQsLfvqjwOO8JDItnhJl0lUqcPpdQV4M/Ai3YNRjNcVy4a+pichqtSAWl
9S1HV01MNeouk8PEr/zoUasmgfO3mz6N6XTUtF/tIi8K2kBOsLAtqltihFSd/zT8
ifYZE9cZTJ09lUs7kMz1wxFIsiegaE1jUYV+VSLu3PJ97oKhQpqop8EnkBAoBl6r
mdmFryBQIdakPIdd4rO5Yg+to10n4u7Wij9ePIwWMfbqY4QoW5nXqMgFJQkIt4TG
eQIDAQAB
-----END PUBLIC KEY-----

The production API's RSA public key is as follows:

% cat prod.pem
-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA7wx4l7P3eLsaEyK7ZRME
g5urEHwaEoY9LjkYcpMw9gmPIi3RoGjQX7HzPad2D7ES2yIGdmyxjN8R2LyFa8ke
EE+VY3ISYzP2cOjd/zDkX01yjDXQLRxntXbtqIypGQAzmZbCyIB226ZKEE+ldh6M
YyM41YWYikfocYssFEjY7fpPGeUg4FOmHmyWIZeMkXYovskoi1jZ1Ay1qn95XlpA
/Ptru2efro4T1xksv4WBBrj8bMNwdDpf4oyzH2PKYkn3/KlNTBCHlAmzP0jd4pIa
N0tAf2m8TcNq7kuBzyfs8AcCUj870p8SEiko0PMx6K+zVsTVWsxfUX+/+kmapmp/
AwIDAQAB
-----END PUBLIC KEY-----

NOTE: Password must be at least 20 characters long, have lower and upper case letters, numbers, and special characters.

NOTE: Phone number must be provided with country code, e.g. +358404982201.

RegisterReq

Account parameters

Email: string
in path

Email address as the account username, e.g. dan.forsberg@isecure.fi

Mode: string admin, data
in path

Administer account with admin mode, exchange files with data mode

Request Content-Types: application/json
Request Example
{
  "ApiKey": "hzYAVO9Sg98nsNh81M84O2kyXVy6K1xwHD8",
  "ChResp": "ezwXceQ63fV9oWTSJBAE2Zq1Cw5tBIJe+7+Rl8jrgbk=|1475429754114|4017bda8-0a15-4154-a8b7-88069b05cb4e",
  "Company": "ISECure Oy",
  "Encrypted": "...",
  "Name": "Dan Forsberg",
  "Phone": "+358404835507"
}
201 Created
RegisterResp

Operation succesfully processed. Resource created. See response.

400 Bad Request
ErrorResponse

Request validation error

500 Internal Server Error
ErrorResponse

Unexpected error occurred

Response Content-Types: application/json
Response Example (201 Created) 
{
  "ApiKey": "4vN6hGHrav31smM0Ha1k15MDlZKOEGn43UToWTt2",
  "ResponseCode": "..",
  "ResponseText": ".."
}
Response Example (400 Bad Request) 
{
  "RequestId": "string",
  "ResponseCode": "string",
  "ResponseText": "string"
}
Response Example (500 Internal Server Error) 
{
  "RequestId": "string",
  "ResponseCode": "string",
  "ResponseText": "string"
}
Account

InitPasswordReset

GET /account/{Email}/{Mode}/password

Start password reset by getting confirmation SMS code.

Email: string
in path

Email address as the account username, e.g. dan.forsberg@isecure.fi

Mode: string admin, data
in path

Administer account with admin mode, exchange files with data mode

200 OK
Response

Operation succesfully processed. See response.

400 Bad Request
ErrorResponse

Request validation error

500 Internal Server Error
ErrorResponse

Unexpected error occurred

Response Content-Types: application/json
Response Example (200 OK) 
{
  "ResponseCode": "string",
  "ResponseText": "string"
}
Response Example (400 Bad Request) 
{
  "RequestId": "string",
  "ResponseCode": "string",
  "ResponseText": "string"
}
Response Example (500 Internal Server Error) 
{
  "RequestId": "string",
  "ResponseCode": "string",
  "ResponseText": "string"
}
Account

PasswordReset

POST /account/{Email}/{Mode}/password

Set new password for user with Email. Provide received SMS Code.

NOTE: the password must be encrypted, see Register for more details.

PasswordResetReq

Account parameters

Email: string
in path

Email address as the account username, e.g. dan.forsberg@isecure.fi

Mode: string admin, data
in path

Administer account with admin mode, exchange files with data mode

Request Content-Types: application/json
Request Example
{
  "ChResp": "ezwXceQ63fV9oWTSJBAE2Zq1Cw5tBIJe+7+Rl8jrgbk=|1475429754114|4017bda8-0a15-4154-a8b7-88069b05cb4e",
  "Code": "123456",
  "Encrypted": "..."
}
200 OK
Response

Operation succesfully processed. See response.

400 Bad Request
ErrorResponse

Request validation error

500 Internal Server Error
ErrorResponse

Unexpected error occurred

Response Content-Types: application/json
Response Example (200 OK) 
{
  "ResponseCode": "string",
  "ResponseText": "string"
}
Response Example (400 Bad Request) 
{
  "RequestId": "string",
  "ResponseCode": "string",
  "ResponseText": "string"
}
Response Example (500 Internal Server Error) 
{
  "RequestId": "string",
  "ResponseCode": "string",
  "ResponseText": "string"
}
Account

VerifyPhone

POST /account/{Email}/{Mode}/{Phone}

Confirm phone number for Email Mode user, with Code received via SMS.

NOTE: Phone and EMail verification can be bypassed per API key on request to dan.forsberg@isecure.fi . E.g. if integrator verifies EMail and Phone beforehand.

VerifyPhoneReq

Account parameters

Email: string
in path

Email address as the account username, e.g. dan.forsberg@isecure.fi

Mode: string admin, data
in path

Administer account with admin mode, exchange files with data mode

Phone: string
in path

Phone number with country code, e.g. +358401234567

Request Content-Types: application/json
Request Example
{
  "Code": "123456"
}
200 OK
Response

Operation succesfully processed. See response.

400 Bad Request
ErrorResponse

Request validation error

500 Internal Server Error
ErrorResponse

Unexpected error occurred

Response Content-Types: application/json
Response Example (200 OK) 
{
  "ResponseCode": "string",
  "ResponseText": "string"
}
Response Example (400 Bad Request) 
{
  "RequestId": "string",
  "ResponseCode": "string",
  "ResponseText": "string"
}
Response Example (500 Internal Server Error) 
{
  "RequestId": "string",
  "ResponseCode": "string",
  "ResponseText": "string"
}

Certs

Certs

ListCerts

GET /certs/

List certs from all banks

Authorization: string
in header

Use IdToken from the Login response as the Authorization header

x-api-key: string
in header

Use ApiKey from the Login response as the x-api-key header

200 OK
ListCertsResp

Operation succesfully processed. See response.

400 Bad Request
ErrorResponse

Request validation error

401 Unauthorized
ErrorResponse

Unauthorized

403 Forbidden
ErrorResponse

Unauthenticated

500 Internal Server Error
ErrorResponse

Unexpected error occurred

Response Content-Types: application/json
Response Example (200 OK) 
{
  "ResponseCode": "..",
  "ResponseText": ".."
}
Response Example (400 Bad Request) 
{
  "RequestId": "string",
  "ResponseCode": "string",
  "ResponseText": "string"
}
Response Example (401 Unauthorized) 
{
  "RequestId": "string",
  "ResponseCode": "string",
  "ResponseText": "string"
}
Response Example (403 Forbidden) 
{
  "RequestId": "string",
  "ResponseCode": "string",
  "ResponseText": "string"
}
Response Example (500 Internal Server Error) 
{
  "RequestId": "string",
  "ResponseCode": "string",
  "ResponseText": "string"
}
Authorizer
X-Api-Key
Certs

ConfigCerts

POST /certs/

Configure certificate usage parameters. Currently, only settable (permanent) parameter is export. Set it to disabled for disallowing private key export.

NOTE: When export is disabled it is permanent, it can not be re-enabled through the API (safety feature).

ConfigCertsReq

Certs handling settings

Authorization: string
in header

Use IdToken from the Login response as the Authorization header

x-api-key: string
in header

Use ApiKey from the Login response as the x-api-key header

Request Content-Types: application/json
Request Example
{
  "Export": "disabled"
}
200 OK
Response

Operation succesfully processed. See response.

400 Bad Request
ErrorResponse

Request validation error

401 Unauthorized
ErrorResponse

Unauthorized

403 Forbidden
ErrorResponse

Unauthenticated

500 Internal Server Error
ErrorResponse

Unexpected error occurred

Response Content-Types: application/json
Response Example (200 OK) 
{
  "ResponseCode": "string",
  "ResponseText": "string"
}
Response Example (400 Bad Request) 
{
  "RequestId": "string",
  "ResponseCode": "string",
  "ResponseText": "string"
}
Response Example (401 Unauthorized) 
{
  "RequestId": "string",
  "ResponseCode": "string",
  "ResponseText": "string"
}
Response Example (403 Forbidden) 
{
  "RequestId": "string",
  "ResponseCode": "string",
  "ResponseText": "string"
}
Response Example (500 Internal Server Error) 
{
  "RequestId": "string",
  "ResponseCode": "string",
  "ResponseText": "string"
}
Authorizer
X-Api-Key
Certs

UnshareCerts

DELETE /certs/shared/{ExtEmail}

Unshare certs with an existing ExtEmail account.

Authorization: string
in header

Use IdToken from the Login response as the Authorization header

x-api-key: string
in header

Use ApiKey from the Login response as the x-api-key header

ExtEmail: string
in path

Unshare certs with ExtEMail account.

200 OK
UnshareCertsResp

Operation succesfully processed. See response.

400 Bad Request
ErrorResponse

Request validation error

401 Unauthorized
ErrorResponse

Unauthorized

403 Forbidden
ErrorResponse

Unauthenticated

500 Internal Server Error
ErrorResponse

Unexpected error occurred

Response Content-Types: application/json
Response Example (200 OK) 
{
  "ResponseCode": "..",
  "ResponseText": "..",
  "SharedFrom": "string",
  "SharedTo": "string"
}
Response Example (400 Bad Request) 
{
  "RequestId": "string",
  "ResponseCode": "string",
  "ResponseText": "string"
}
Response Example (401 Unauthorized) 
{
  "RequestId": "string",
  "ResponseCode": "string",
  "ResponseText": "string"
}
Response Example (403 Forbidden) 
{
  "RequestId": "string",
  "ResponseCode": "string",
  "ResponseText": "string"
}
Response Example (500 Internal Server Error) 
{
  "RequestId": "string",
  "ResponseCode": "string",
  "ResponseText": "string"
}
Authorizer
X-Api-Key
Certs

ShareCerts

PUT /certs/shared/{ExtEmail}

Share certs with an existing account ExtEmail under the same API Key.

If the ExtEmail account does not have the specific bank certificate (key pair), then certs (key pair) from this account will be used (shared), if any. Both accounts must be registered and using the same integrator API Key.

Authorization: string
in header

Use IdToken from the Login response as the Authorization header

x-api-key: string
in header

Use ApiKey from the Login response as the x-api-key header

ExtEmail: string
in path

Share certs with ExtEMail account.

201 Created
ShareCertsResp

Operation succesfully processed. Resource created. See response.

400 Bad Request
ErrorResponse

Request validation error

401 Unauthorized
ErrorResponse

Unauthorized

403 Forbidden
ErrorResponse

Unauthenticated

500 Internal Server Error
ErrorResponse

Unexpected error occurred

Response Content-Types: application/json
Response Example (201 Created) 
{
  "ResponseCode": "..",
  "ResponseText": "..",
  "SharedFrom": "string",
  "SharedTo": "string"
}
Response Example (400 Bad Request) 
{
  "RequestId": "string",
  "ResponseCode": "string",
  "ResponseText": "string"
}
Response Example (401 Unauthorized) 
{
  "RequestId": "string",
  "ResponseCode": "string",
  "ResponseText": "string"
}
Response Example (403 Forbidden) 
{
  "RequestId": "string",
  "ResponseCode": "string",
  "ResponseText": "string"
}
Response Example (500 Internal Server Error) 
{
  "RequestId": "string",
  "ResponseCode": "string",
  "ResponseText": "string"
}
Authorizer
X-Api-Key
Certs

ExportCert

GET /certs/{Bank}

Download bank certificate and private key encrypted with stored PGP key.

NOTE: The previously uploaded PgpKeyId must have purpose type export. I.e. purpose type authorize PGP keys can not be used for exporting.

NOTE: If export has been set to disabled (see ConfigCerts), then exporting private keys is not possible through API.

Authorization: string
in header

Use IdToken from the Login response as the Authorization header

x-api-key: string
in header

Use ApiKey from the Login response as the x-api-key header

Bank: string
in path

Bank used for this operation, can have values of nordea, osuuspankki, danskebank, aktia, sp, shb, pop, spankki, or alandsbanken.

PgpKeyId: string
in query

Short version of a PGP Key id idenfiying the exported Private Key, e.g. 3A3A59B2

200 OK
ExportCertResp

Operation succesfully processed. See response.

400 Bad Request
ErrorResponse

Request validation error

401 Unauthorized
ErrorResponse

Unauthorized

403 Forbidden
ErrorResponse

Unauthenticated

500 Internal Server Error
ErrorResponse

Unexpected error occurred

Response Content-Types: application/json
Response Example (200 OK) 
{
  "ResponseCode": "..",
  "ResponseText": ".."
}
Response Example (400 Bad Request) 
{
  "RequestId": "string",
  "ResponseCode": "string",
  "ResponseText": "string"
}
Response Example (401 Unauthorized) 
{
  "RequestId": "string",
  "ResponseCode": "string",
  "ResponseText": "string"
}
Response Example (403 Forbidden) 
{
  "RequestId": "string",
  "ResponseCode": "string",
  "ResponseText": "string"
}
Response Example (500 Internal Server Error) 
{
  "RequestId": "string",
  "ResponseCode": "string",
  "ResponseText": "string"
}
Authorizer
X-Api-Key
Certs

EnrollCert

POST /certs/{Bank}

Provide WS-Channel user id, WsUserId, Company, and PIN Code for Bank certificate enrollment. Company must match with the contract with the bank and is part of enrollment process. Note that certificate private key is securely generated and stored encrypted with AWS KMS encrypted authentication on API side. Certificates are automatically renewed when needed.

NOTE: For OP bank, ensure that you set the PIN code blocks 1 and 2 in correct order. If not initially in correct order, bank will lock the registration and you need to call them for unlock.

EnrollCertReq

Certs parameters

Authorization: string
in header

Use IdToken from the Login response as the Authorization header

x-api-key: string
in header

Use ApiKey from the Login response as the x-api-key header

Bank: string
in path

Bank used for this operation, can have values of nordea, osuuspankki, danskebank, aktia, sp, shb, pop, spankki, or alandsbanken.

Request Content-Types: application/json
Request Example
{
  "Code": "8642603384107437",
  "Company": "ISECURE OY",
  "WsUserId": "..."
}
201 Created
Response

Operation succesfully processed. Resource created. See response.

400 Bad Request
ErrorResponse

Request validation error

401 Unauthorized
ErrorResponse

Unauthorized

403 Forbidden
ErrorResponse

Unauthenticated

500 Internal Server Error
ErrorResponse

Unexpected error occurred

Response Content-Types: application/json
Response Example (201 Created) 
{
  "ResponseCode": "string",
  "ResponseText": "string"
}
Response Example (400 Bad Request) 
{
  "RequestId": "string",
  "ResponseCode": "string",
  "ResponseText": "string"
}
Response Example (401 Unauthorized) 
{
  "RequestId": "string",
  "ResponseCode": "string",
  "ResponseText": "string"
}
Response Example (403 Forbidden) 
{
  "RequestId": "string",
  "ResponseCode": "string",
  "ResponseText": "string"
}
Response Example (500 Internal Server Error) 
{
  "RequestId": "string",
  "ResponseCode": "string",
  "ResponseText": "string"
}
Authorizer
X-Api-Key
Certs

ImportCert

PUT /certs/{Bank}

Provide WsUserId, Company, PrivateKey, and Certificate for importing existing WS Channel certificate and private key. Company must match with the contract with the bank. Certificate(s) and private key(s) must be PEM formatted.

NOTE: EncCcertificate and EncPrivatekey are for DanskeBank only.

ImportCertReq

Certs parameters

Authorization: string
in header

Use IdToken from the Login response as the Authorization header

x-api-key: string
in header

Use ApiKey from the Login response as the x-api-key header

Bank: string
in path

Bank used for this operation, can have values of nordea, osuuspankki, danskebank, aktia, sp, shb, pop, spankki, or alandsbanken.

Request Content-Types: application/json
Request Example
{
  "Certificate": "...",
  "Company": "ISECURE OY",
  "EncCertificate": "...",
  "EncPrivatekey": "...",
  "PrivateKey": "...",
  "WsUserId": "..."
}
201 Created
Response

Operation succesfully processed. Resource created. See response.

400 Bad Request
ErrorResponse

Request validation error

401 Unauthorized
ErrorResponse

Unauthorized

403 Forbidden
ErrorResponse

Unauthenticated

500 Internal Server Error
ErrorResponse

Unexpected error occurred

Response Content-Types: application/json
Response Example (201 Created) 
{
  "ResponseCode": "string",
  "ResponseText": "string"
}
Response Example (400 Bad Request) 
{
  "RequestId": "string",
  "ResponseCode": "string",
  "ResponseText": "string"
}
Response Example (401 Unauthorized) 
{
  "RequestId": "string",
  "ResponseCode": "string",
  "ResponseText": "string"
}
Response Example (403 Forbidden) 
{
  "RequestId": "string",
  "ResponseCode": "string",
  "ResponseText": "string"
}
Response Example (500 Internal Server Error) 
{
  "RequestId": "string",
  "ResponseCode": "string",
  "ResponseText": "string"
}
Authorizer
X-Api-Key

Files

Files

ListFiles

GET /files/{Bank}

Asks bank to list downloadable files matching filters. Status can be e.g. NEW, ALL, or DLD. Filetype is bank specific (ALL is not accepted), see bank specification. Bank is the name of the bank. Returns a list of FileDescriptors.

NOTE: Certificate must be enrolled before files can be listed, downloaded or uploaded.

NOTE: The uploaded files do not show up on the file listing.

% export SESSION=~/.wscli/settings.yaml
% wscli session login -c $SESSION
%
% curl -H Authorization:`yq -r .settings.idtoken $SESSION` \ 
       -H x-api-key:`yq -r .settings.apikey $SESSION` \ 
       https://ws-api.isecure.fi/v2/files/danskebank
Authorization: string
in header

Use IdToken from the Login response as the Authorization header

x-api-key: string
in header

Use ApiKey from the Login response as the x-api-key header

Bank: string
in path

Bank used for this operation, can have values of nordea, osuuspankki, danskebank, aktia, sp, shb, pop, spankki, alandsbanken or SEB.

Status: string
in query

Status of the file, e.g. ALL. NEW, DLD

FileType: string
in query

Bank specific FileType identifies the file type to be listed

200 OK
ListFilesResp

Operation succesfully processed. See response.

400 Bad Request
ErrorResponse

Request validation error

401 Unauthorized
ErrorResponse

Unauthorized

403 Forbidden
ErrorResponse

Unauthenticated

500 Internal Server Error
ErrorResponse

Unexpected error occurred

Response Content-Types: application/json
Response Example (200 OK) 
{
  "ResponseCode": "..",
  "ResponseText": ".."
}
Response Example (400 Bad Request) 
{
  "RequestId": "string",
  "ResponseCode": "string",
  "ResponseText": "string"
}
Response Example (401 Unauthorized) 
{
  "RequestId": "string",
  "ResponseCode": "string",
  "ResponseText": "string"
}
Response Example (403 Forbidden) 
{
  "RequestId": "string",
  "ResponseCode": "string",
  "ResponseText": "string"
}
Response Example (500 Internal Server Error) 
{
  "RequestId": "string",
  "ResponseCode": "string",
  "ResponseText": "string"
}
Authorizer
X-Api-Key
Files

UploadFile

PUT /files/{Bank}

Uploads file to bank if PGP signature(s) are valid. FileContents is a string of Base64 encoded file contents. FileType is bank specific. Signature is detached PGP signature or concatenation of PGP detached signatures in ASCII armor format. PGP signatures are used for authorizing file uploads. Currently one valid PGP authorize registered key signature is enough. FileName is upload filename.

NOTE: The uploaded files do not show up on the file listing from bank.

% export SESSION=~/.wscli/settings.yaml
% wscli session login -c $SESSION
% export APIKEY=`yq -r .settings.apikey $SESSION`
% export IDTOKEN=`yq -r .settings.idtoken $SESSION`
%
% curl -X PUT -H Content-Type:application/json \ 
       -H Authorization:$IDTOKEN \ 
       -H x-api-key:$APIKEY \ 
       -d @request-example.json \ 
       https://ws-api.isecure.fi/v2/files/danskebank
UploadFileReq

Files parameters

Authorization: string
in header

Use IdToken from the Login response as the Authorization header

x-api-key: string
in header

Use ApiKey from the Login response as the x-api-key header

Bank: string
in path

Bank used for this operation, can have values of nordea, osuuspankki, danskebank, aktia, sp, shb, pop, spankki, alandsbanken or SEB.

Request Content-Types: application/json
Request Example
{
  "FileContents": "...",
  "FileName": "testfile",
  "FileType": "KTL",
  "Signature": "string"
}
201 Created
Response

Operation succesfully processed. Resource created. See response.

400 Bad Request
ErrorResponse

Request validation error

401 Unauthorized
ErrorResponse

Unauthorized

403 Forbidden
ErrorResponse

Unauthenticated

500 Internal Server Error
ErrorResponse

Unexpected error occurred

Response Content-Types: application/json
Response Example (201 Created) 
{
  "ResponseCode": "string",
  "ResponseText": "string"
}
Response Example (400 Bad Request) 
{
  "RequestId": "string",
  "ResponseCode": "string",
  "ResponseText": "string"
}
Response Example (401 Unauthorized) 
{
  "RequestId": "string",
  "ResponseCode": "string",
  "ResponseText": "string"
}
Response Example (403 Forbidden) 
{
  "RequestId": "string",
  "ResponseCode": "string",
  "ResponseText": "string"
}
Response Example (500 Internal Server Error) 
{
  "RequestId": "string",
  "ResponseCode": "string",
  "ResponseText": "string"
}
Authorizer
X-Api-Key
Files

DeleteFile

DELETE /files/{Bank}/{FileType}/{FileReference}

Deletes file on bank side. File is identified with filereference.

Authorization: string
in header

Use IdToken from the Login response as the Authorization header

x-api-key: string
in header

Use ApiKey from the Login response as the x-api-key header

Bank: string
in path

Bank used for this operation, can have values of nordea, osuuspankki, danskebank, aktia, sp, shb, pop, spankki, alandsbanken or SEB.

FileType: string
in path

File reference id from list files

FileReference: string
in path

File reference id from list files

200 OK
Response

Operation succesfully processed. See response.

400 Bad Request
ErrorResponse

Request validation error

401 Unauthorized
ErrorResponse

Unauthorized

403 Forbidden
ErrorResponse

Unauthenticated

500 Internal Server Error
ErrorResponse

Unexpected error occurred

Response Content-Types: application/json
Response Example (200 OK) 
{
  "ResponseCode": "string",
  "ResponseText": "string"
}
Response Example (400 Bad Request) 
{
  "RequestId": "string",
  "ResponseCode": "string",
  "ResponseText": "string"
}
Response Example (401 Unauthorized) 
{
  "RequestId": "string",
  "ResponseCode": "string",
  "ResponseText": "string"
}
Response Example (403 Forbidden) 
{
  "RequestId": "string",
  "ResponseCode": "string",
  "ResponseText": "string"
}
Response Example (500 Internal Server Error) 
{
  "RequestId": "string",
  "ResponseCode": "string",
  "ResponseText": "string"
}
Authorizer
X-Api-Key
Files

DownloadFile

GET /files/{Bank}/{FileType}/{FileReference}

Downloads file identified with filereference, filetype, and bank. Filereference is received in file list from bank. Returns base64 encoded file content.

Authorization: string
in header

Use IdToken from the Login response as the Authorization header

x-api-key: string
in header

Use ApiKey from the Login response as the x-api-key header

Bank: string
in path

Bank used for this operation, can have values of nordea, osuuspankki, danskebank, aktia, sp, shb, pop, spankki, alandsbanken or SEB.

FileType: string
in path

File type from list files

FileReference: string
in path

File reference identifier from list files

200 OK
DownloadFileResp

Operation succesfully processed. See response.

400 Bad Request
ErrorResponse

Request validation error

401 Unauthorized
ErrorResponse

Unauthorized

403 Forbidden
ErrorResponse

Unauthenticated

500 Internal Server Error
ErrorResponse

Unexpected error occurred

Response Content-Types: application/json
Response Example (200 OK) 
{
  "Content": "xxxxxxxx",
  "ResponseCode": "..",
  "ResponseText": ".."
}
Response Example (400 Bad Request) 
{
  "RequestId": "string",
  "ResponseCode": "string",
  "ResponseText": "string"
}
Response Example (401 Unauthorized) 
{
  "RequestId": "string",
  "ResponseCode": "string",
  "ResponseText": "string"
}
Response Example (403 Forbidden) 
{
  "RequestId": "string",
  "ResponseCode": "string",
  "ResponseText": "string"
}
Response Example (500 Internal Server Error) 
{
  "RequestId": "string",
  "ResponseCode": "string",
  "ResponseText": "string"
}
Authorizer
X-Api-Key

Integrator

Integrator

ListAccounts

GET /integrator/accounts

List accounts registered under the integrator's API key. Account that created the API key is authorized to call this.

Authorization: string
in header

Use IdToken from the Login response as the Authorization header

x-api-key: string
in header

Use ApiKey from the Login response as the x-api-key header

200 OK
ListAccountsResp

Operation succesfully processed. See response.

400 Bad Request
ErrorResponse

Request validation error

401 Unauthorized
ErrorResponse

Unauthorized

403 Forbidden
ErrorResponse

Unauthenticated

500 Internal Server Error
ErrorResponse

Unexpected error occurred

Response Content-Types: application/json
Response Example (200 OK) 
{
  "ResponseCode": "..",
  "ResponseText": ".."
}
Response Example (400 Bad Request) 
{
  "RequestId": "string",
  "ResponseCode": "string",
  "ResponseText": "string"
}
Response Example (401 Unauthorized) 
{
  "RequestId": "string",
  "ResponseCode": "string",
  "ResponseText": "string"
}
Response Example (403 Forbidden) 
{
  "RequestId": "string",
  "ResponseCode": "string",
  "ResponseText": "string"
}
Response Example (500 Internal Server Error) 
{
  "RequestId": "string",
  "ResponseCode": "string",
  "ResponseText": "string"
}
Authorizer
X-Api-Key

Pgp

Pgp

DeleteKey

DELETE /pgp

Delete PGP key.

DeleteKeyReq

Pgp parameters

Authorization: string
in header

Use IdToken from the Login response as the Authorization header

x-api-key: string
in header

Use ApiKey from the Login response as the x-api-key header

Request Example
{
  "PgpKeyId": "DBCBE671"
}
200 OK
DeleteKeyResp

Operation succesfully processed. See response.

400 Bad Request
ErrorResponse

Request validation error

401 Unauthorized
ErrorResponse

Unauthorized

403 Forbidden
ErrorResponse

Unauthenticated

500 Internal Server Error
ErrorResponse

Unexpected error occurred

Response Content-Types: application/json
Response Example (200 OK) 
{
  "ResponseCode": "..",
  "ResponseText": ".."
}
Response Example (400 Bad Request) 
{
  "RequestId": "string",
  "ResponseCode": "string",
  "ResponseText": "string"
}
Response Example (401 Unauthorized) 
{
  "RequestId": "string",
  "ResponseCode": "string",
  "ResponseText": "string"
}
Response Example (403 Forbidden) 
{
  "RequestId": "string",
  "ResponseCode": "string",
  "ResponseText": "string"
}
Response Example (500 Internal Server Error) 
{
  "RequestId": "string",
  "ResponseCode": "string",
  "ResponseText": "string"
}
Authorizer
X-Api-Key
Pgp

ListKeys

GET /pgp

List PGP keys.

Authorization: string
in header

Use IdToken from the Login response as the Authorization header

x-api-key: string
in header

Use ApiKey from the Login response as the x-api-key header

200 OK
ListKeysResp

Operation succesfully processed. See response.

400 Bad Request
ErrorResponse

Request validation error

401 Unauthorized
ErrorResponse

Unauthorized

403 Forbidden
ErrorResponse

Unauthenticated

500 Internal Server Error
ErrorResponse

Unexpected error occurred

Response Content-Types: application/json
Response Example (200 OK) 
{
  "ResponseCode": "..",
  "ResponseText": ".."
}
Response Example (400 Bad Request) 
{
  "RequestId": "string",
  "ResponseCode": "string",
  "ResponseText": "string"
}
Response Example (401 Unauthorized) 
{
  "RequestId": "string",
  "ResponseCode": "string",
  "ResponseText": "string"
}
Response Example (403 Forbidden) 
{
  "RequestId": "string",
  "ResponseCode": "string",
  "ResponseText": "string"
}
Response Example (500 Internal Server Error) 
{
  "RequestId": "string",
  "ResponseCode": "string",
  "ResponseText": "string"
}
Authorizer
X-Api-Key
Pgp

UploadKey

PUT /pgp

Upload PGP key.

UploadKeyReq

ASCII armored PGP Key in PgpKey and key purpose, i.e. export (exporting cert private key) or authorize (upload content authorization verification) in PgpKeyPurpose.

NOTE: The same PGP key can not be used for both export and authorize purpose at the same time.

Authorization: string
in header

Use IdToken from the Login response as the Authorization header

x-api-key: string
in header

Use ApiKey from the Login response as the x-api-key header

Request Content-Types: application/json
Request Example
{
  "PgpKey": "...",
  "PgpKeyPurpose": "authorize"
}
201 Created
Response

Operation succesfully processed. Resource created. See response.

400 Bad Request
ErrorResponse

Request validation error

401 Unauthorized
ErrorResponse

Unauthorized

403 Forbidden
ErrorResponse

Unauthenticated

500 Internal Server Error
ErrorResponse

Unexpected error occurred

Response Content-Types: application/json
Response Example (201 Created) 
{
  "ResponseCode": "string",
  "ResponseText": "string"
}
Response Example (400 Bad Request) 
{
  "RequestId": "string",
  "ResponseCode": "string",
  "ResponseText": "string"
}
Response Example (401 Unauthorized) 
{
  "RequestId": "string",
  "ResponseCode": "string",
  "ResponseText": "string"
}
Response Example (403 Forbidden) 
{
  "RequestId": "string",
  "ResponseCode": "string",
  "ResponseText": "string"
}
Response Example (500 Internal Server Error) 
{
  "RequestId": "string",
  "ResponseCode": "string",
  "ResponseText": "string"
}
Authorizer
X-Api-Key

Session

Session

Logout

DELETE /session/{Email}/{Mode}

Logout user.

NOTE: AWS Cognito allows user logout, but the received authorization IdToken is still valid. When the optional AccessToken parameter is also provided, the IdToken is also revoked.

Authorization: string
in header

Use IdToken from the Login response as the Authorization header

x-api-key: string
in header

Use ApiKey from the Login response as the x-api-key header

Email: string
in path

Email address as the account username, e.g. dan.forsberg@isecure.fi

Mode: string admin, data
in path

Administer account with admin mode, exchange files with data mode

200 OK
Response

Operation succesfully processed. See response.

400 Bad Request
ErrorResponse

Request validation error

401 Unauthorized
ErrorResponse

Unauthorized

403 Forbidden
ErrorResponse

Unauthenticated

500 Internal Server Error
ErrorResponse

Unexpected error occurred

Response Content-Types: application/json
Response Example (200 OK) 
{
  "ResponseCode": "string",
  "ResponseText": "string"
}
Response Example (400 Bad Request) 
{
  "RequestId": "string",
  "ResponseCode": "string",
  "ResponseText": "string"
}
Response Example (401 Unauthorized) 
{
  "RequestId": "string",
  "ResponseCode": "string",
  "ResponseText": "string"
}
Response Example (403 Forbidden) 
{
  "RequestId": "string",
  "ResponseCode": "string",
  "ResponseText": "string"
}
Response Example (500 Internal Server Error) 
{
  "RequestId": "string",
  "ResponseCode": "string",
  "ResponseText": "string"
}
Authorizer
X-Api-Key
Session

InitLogin

GET /session/{Email}/{Mode}

Before login, client must fetch challenge from the API. Then on login, the challenge must be passed along to the API (as response to the challenge). The challenge is always fresh for some period of time and the API validates it when passed with login. The challenge has form of base64-string|timestamp|uuid. For example:

ezwXceQ63fV9oWTSJBAE2Zq1Cw5tBIJe+7+Rl8jrgbk=|1475429754114|4017bda8-0a15-4154-a8b7-88069b05cb4e

NOTE: The call must contain the same email as used for registration itself.

Email: string
in path

Email address as the account username, e.g. dan.forsberg@isecure.fi

Mode: string admin, data
in path

Administer account with admin mode, exchange files with data mode

200 OK
InitLoginResp

Operation succesfully processed. See response.

400 Bad Request
ErrorResponse

Request validation error

500 Internal Server Error
ErrorResponse

Unexpected error occurred

Response Content-Types: application/json
Response Example (200 OK) 
{
  "Challenge": "9Ty4zrnJGqNH0i1+I0OTKHjTs03Ymd4tBH70FTiYNhA=|1494962070679|2646b71b-9b51-4d11-bf5e-cca5617bcfde",
  "ResponseCode": "..",
  "ResponseText": ".."
}
Response Example (400 Bad Request) 
{
  "RequestId": "string",
  "ResponseCode": "string",
  "ResponseText": "string"
}
Response Example (500 Internal Server Error) 
{
  "RequestId": "string",
  "ResponseCode": "string",
  "ResponseText": "string"
}
Session

Login

POST /session/{Email}/{Mode}

After getchallenge, call login with Email, Mode, and RSA encrypted admin or data account password and challenge timestamp. For further API calls (requiring authorization), include the received IdToken into the Authorization header of the request (pass idtoken as required parameter with the client SDK API calls). The IdToken expires in ExpiresIn seconds, after which new login must be performed.

NOTE: In case SMS Code is required, the call returns only Session, ResponseCode, and ResponseText as the login process continues with the LoginMFA API call.

NOTE: If Email has not been yet verified, successful login provides only ResponseCode, ResponseText, and an AccessToken that must be used to verify email address.

% CHALLENGE=`curl -s https://ws-api.test.isecure.fi/v2/session/dan.forsberg@isecure.fi/data | jq -r .Challenge`
% TIMESTAMP=`echo $CHALLENGE | cut -f 2 -d \|`
% ENCRYPTED=`echo -n testPassword..123455677098811\|\|$TIMESTAMP | openssl rsautl -oaep -encrypt -pubin -inkey test.pem | base64
LoginReq

Login body parameters

Email: string
in path

Email address as the account username, e.g. dan.forsberg@isecure.fi

Mode: string admin, data
in path

Administer account with admin mode, exchange files with data mode

Request Content-Types: application/json
Request Example
{
  "ChResp": "ezwXceQ63fV9oWTSJBAE2Zq1Cw5tBIJe+7+Rl8jrgbk=|1475429754114|4017bda8-0a15-4154-a8b7-88069b05cb4e",
  "Encrypted": "..."
}
200 OK
LoginResp

Operation succesfully processed. See response.

400 Bad Request
ErrorResponse

Request validation error

500 Internal Server Error
ErrorResponse

Unexpected error occurred

Response Content-Types: application/json
Response Example (200 OK) 
{
  "AccessToken": "eyJraWQiO...CzzcdcdAdEzKIcJPR7Fda0A",
  "ApiKey": "4vN6hGHrav31smM0Ha1k15MDlZKOEGn43UToWTt2",
  "ExpiresIn": "3600",
  "IdToken": "eyJraWQiOiJ...jExlzbFU4GlGtml7AWQHDYi05IpA",
  "ResponseCode": "..",
  "ResponseText": "..",
  "Session": "xxxxxxxx"
}
Response Example (400 Bad Request) 
{
  "RequestId": "string",
  "ResponseCode": "string",
  "ResponseText": "string"
}
Response Example (500 Internal Server Error) 
{
  "RequestId": "string",
  "ResponseCode": "string",
  "ResponseText": "string"
}
Session

LoginMFA

PUT /session/{Email}/{Mode}/mfacode

Send SMS Code along with previously received Session token. If Email has not been yet verified, successful login provides only ResponseCode, ResponseText, and an AccessToken that must be used to verify email address. If email is already verified and the login succeeds, add the IdToken from the login response as Authorization header in API requests requiring authorization (i.e. pass as parameter to client SDK API calls). IdToken expires in ExpiresIn seconds.

LoginMFAReq

Session parameters

Email: string
in path

Email address as the account username, e.g. dan.forsberg@isecure.fi

Mode: string admin, data
in path

Administer account with admin mode, exchange files with data mode

Request Content-Types: application/json
Request Example
{
  "Code": "123456",
  "Session": "..."
}
200 OK
LoginMFAResp

Operation succesfully processed. See response.

400 Bad Request
ErrorResponse

Request validation error

500 Internal Server Error
ErrorResponse

Unexpected error occurred

Response Content-Types: application/json
Response Example (200 OK) 
{
  "AccessToken": "eyJraWQiO...CzzcdcdAdEzKIcJPR7Fda0A",
  "ApiKey": "4vN6hGHrav31smM0Ha1k15MDlZKOEGn43UToWTt2",
  "ExpiresIn": "3600",
  "IdToken": "eyJraWQiOiJ...jExlzbFU4GlGtml7AWQHDYi05IpA",
  "ResponseCode": "..",
  "ResponseText": ".."
}
Response Example (400 Bad Request) 
{
  "RequestId": "string",
  "ResponseCode": "string",
  "ResponseText": "string"
}
Response Example (500 Internal Server Error) 
{
  "RequestId": "string",
  "ResponseCode": "string",
  "ResponseText": "string"
}

Schema Definitions

AccountDescriptor: object

AdminMode: string registered, unregistered

admin mode status

Certs: CertDescriptor
CertDescriptor
DataMode: string registered, unregistered

data mode status

Email: string

Email address as the account username

Export: string disabled, allowed

Status for certificate and private key export allowance. See ConfigCerts.

Name: string

Full name of registrant

Phone: string

Phone number with country code and + in front

Example
{
  "AdminMode": "registered",
  "DataMode": "unregistered",
  "Email": "dan.forsberg@isecure.fi",
  "Name": "Dan Forsberg",
  "Phone": "+358404835507",
  "export": "allowed"
}

CertDescriptor: object

CertName: string

Certificate common name

Expires: string

Date of expiry

Issuer: string

Certificate issuer

PEM: string

Certificate in PEM format

Serial: string

Certificate serial number

Subject: string

Certificate subject

Example
{
  "CertName": "osuuspankki_customer_signing_cert",
  "Expires": "Oct 28 06:30:08 2017 GMT",
  "Issuer": "CUSTOMER TEST OP-Pohjola WS CA",
  "PEM": "-----BEGIN CERTIFICATE-----\nMIIF+DCCA+CgAwIBAgIDEaBdMA0GCS...x0t6Cnd5lyGKg=\n-----END CERTIFICATE-----",
  "Serial": "11A05D",
  "Subject": "1000038023"
}

CertsAndKeys: object

Certificate: string

Certificate in PEM format

EncryptedPrivateKey: string

PGP encrypted ascii armored private key

Example
{
  "Certificate": "string",
  "EncryptedPrivateKey": "string"
}

ConfigCertsReq: object

Export: string

Set export to disabled to disallow certificate and private key pair exporting

Example
{
  "Export": "disabled"
}

DeleteKeyReq: object

PgpKeyId: string

8 chars hexadecimal PGP Key Id (see e.g. gpg --list-keys)

Example
{
  "PgpKeyId": "DBCBE671"
}

DeleteKeyResp: object

PgpKeys: PgpKeyDescriptor

List of PGP keys in API

PgpKeyDescriptor
ResponseCode: string

Two digit response code in string format

ResponseText: string

Human readable response text

Example
{
  "ResponseCode": "..",
  "ResponseText": ".."
}

DownloadFileResp: object

Content: string

Downloaded file content as from bank (e.g. in Base64 form)

ResponseCode: string

Two digit response code in string format

ResponseText: string

Human readable response text

Example
{
  "Content": "xxxxxxxx",
  "ResponseCode": "..",
  "ResponseText": ".."
}

EnrollCertReq: object

Code: string

Full PIN code from bank (e.g. combined from SMS and letter)

Company: string

Company name as registered with bank (e.g. full capital letters, see contract). NOTE: The value of this field is not compared with the account company name set during registration because the format for cert enrollment differs between banks.

WsUserId: string

SEPA WebServices channel user id as in contract with bank

Example
{
  "Code": "8642603384107437",
  "Company": "ISECURE OY",
  "WsUserId": "..."
}

ErrorResponse: object

RequestId: string

Service side request id for problem tracing purposes

ResponseCode: string

Two digit response code in string format

ResponseText: string

Human readable response text

Example
{
  "RequestId": "string",
  "ResponseCode": "string",
  "ResponseText": "string"
}

ExportCertResp: object

CertsAndKeys: CertsAndKeys

List of certificate and encrypted private key pairs

CertsAndKeys
ResponseCode: string

Two digit response code in string format

ResponseText: string

Human readable response text

Example
{
  "ResponseCode": "..",
  "ResponseText": ".."
}

FileDescriptor: object

FileReference: string

File reference id, use e.g. when downloading the file

FileTimestamp: string

Creation time stamp of the file from bank

FileType: string

Bank specific file type

ServiceId: string

Bank specific service id (e.g. bank account number)

Status: string

File download status

TargetId: string

Bank specific target id

Example
{
  "FileReference": "227166",
  "FileTimestamp": "2017-05-20T03:36:21.148+03:00",
  "FileType": "VA",
  "ServiceId": "N/A",
  "Status": "NEW",
  "TargetId": "MLP"
}

ImportCertReq: object

Certificate: string

Certificate in PEM format

Company: string

Company name as registered with bank (e.g. full capital letters without Oy, see contract)

EncCertificate: string

Certificate in PEM format (encryption certificate for DanskeBank)

EncPrivatekey: string

Private key in PEM format (encryption certificate for DanskeBank)

PrivateKey: string

Private key in PEM format

WsUserId: string

SEPA WebServices channel user id as in contract with bank

Example
{
  "Certificate": "...",
  "Company": "ISECURE OY",
  "EncCertificate": "...",
  "EncPrivatekey": "...",
  "PrivateKey": "...",
  "WsUserId": "..."
}

InitLoginResp: object

Challenge: string

Challenge copied from API response

ResponseCode: string

Two digit response code in string format

ResponseText: string

Human readable response text

Example
{
  "Challenge": "9Ty4zrnJGqNH0i1+I0OTKHjTs03Ymd4tBH70FTiYNhA=|1494962070679|2646b71b-9b51-4d11-bf5e-cca5617bcfde",
  "ResponseCode": "..",
  "ResponseText": ".."
}

InitRegisterResp: object

Challenge: string

Challenge copied from API response

ResponseCode: string

Two digit response code in string format

ResponseText: string

Human readable response text

Example
{
  "Challenge": "9Ty4zrnJGqNH0i1+I0OTKHjTs03Ymd4tBH70FTiYNhA=|1494962070679|2646b71b-9b51-4d11-bf5e-cca5617bcfde",
  "ResponseCode": "..",
  "ResponseText": ".."
}

ListAccountsResp: object

Accounts: AccountDescriptor

List of accounts under the API key

AccountDescriptor
ResponseCode: string

Two digit response code in string format

ResponseText: string

Human readable response text

Example
{
  "ResponseCode": "..",
  "ResponseText": ".."
}

ListCertsResp: object

Certs: CertDescriptor

List of certificates

CertDescriptor
ResponseCode: string

Two digit response code in string format

ResponseText: string

Human readable response text

Example
{
  "ResponseCode": "..",
  "ResponseText": ".."
}

ListFilesResp: object

FileDescriptors: FileDescriptor

List of downloadable files from bank

FileDescriptor
ResponseCode: string

Two digit response code in string format

ResponseText: string

Human readable response text

Example
{
  "ResponseCode": "..",
  "ResponseText": ".."
}

ListKeysResp: object

PgpKeys: PgpKeyDescriptor

List of PGP keys in API

PgpKeyDescriptor
ResponseCode: string

Two digit response code in string format

ResponseText: string

Human readable response text

Example
{
  "ResponseCode": "..",
  "ResponseText": ".."
}

LoginMFAReq: object

Code: string

Code from SMS

Session: string

Session token from login response

Example
{
  "Code": "123456",
  "Session": "..."
}

LoginMFAResp: object

AccessToken: string

Access token

  • Only present when Email verification is required
ApiKey: string

Integrator API Key

  • Not present when Email verification is required
ExpiresIn: string

Session expiration time

  • Not present when Email verification is required
IdToken: string

ID token

  • Not present when Email verification is required
ResponseCode: string

Two digit response code in string format

ResponseText: string

Human readable response text

Example
{
  "AccessToken": "eyJraWQiO...CzzcdcdAdEzKIcJPR7Fda0A",
  "ApiKey": "4vN6hGHrav31smM0Ha1k15MDlZKOEGn43UToWTt2",
  "ExpiresIn": "3600",
  "IdToken": "eyJraWQiOiJ...jExlzbFU4GlGtml7AWQHDYi05IpA",
  "ResponseCode": "..",
  "ResponseText": ".."
}

LoginReq: object

ChResp: string

Challenge copied from API response

Encrypted: string

RSA encrypted password and timestamp

Example
{
  "ChResp": "ezwXceQ63fV9oWTSJBAE2Zq1Cw5tBIJe+7+Rl8jrgbk=|1475429754114|4017bda8-0a15-4154-a8b7-88069b05cb4e",
  "Encrypted": "..."
}

LoginResp: object

AccessToken: string

Access token

  • Not present on MFA login initiation, i.e. admin mode
  • Only present when Email verification is required
ApiKey: string

Integrator API Key

  • Not present on MFA login initiation, i.e. admin mode)
ExpiresIn: string

Session expiration time

  • Not present on MFA login initiation, i.e. admin mode)
IdToken: string

ID token

  • Not present on MFA login initiation, i.e. admin mode
ResponseCode: string

Two digit response code in string format

ResponseText: string

Human readable response text

Session: string

Session token

  • Only present on MFA login initiation, i.e. admin mode)
Example
{
  "AccessToken": "eyJraWQiO...CzzcdcdAdEzKIcJPR7Fda0A",
  "ApiKey": "4vN6hGHrav31smM0Ha1k15MDlZKOEGn43UToWTt2",
  "ExpiresIn": "3600",
  "IdToken": "eyJraWQiOiJ...jExlzbFU4GlGtml7AWQHDYi05IpA",
  "ResponseCode": "..",
  "ResponseText": "..",
  "Session": "xxxxxxxx"
}

PasswordResetReq: object

ChResp: string

Challenge copied from API response

Code: string

Code from SMS

Encrypted: string

RSA encrypted NEW password and timestamp

Example
{
  "ChResp": "ezwXceQ63fV9oWTSJBAE2Zq1Cw5tBIJe+7+Rl8jrgbk=|1475429754114|4017bda8-0a15-4154-a8b7-88069b05cb4e",
  "Code": "123456",
  "Encrypted": "..."
}

PgpKeyDescriptor: object

PgpKeyId: string

Short version of a PGP Key id idenfiying the key, e.g. 3A3A59B2

PgpKeyPurpose: string export, authorize

PGP Key purpose

Example
{
  "PgpKeyId": "3A3A59B2",
  "PgpKeyPurpose": "authorize"
}

RegisterReq: object

ApiKey: string

Integrator API Key, or 0 if not already known (e.g. initial integrator registration)

ChResp: string

Challenge copied from API response

Company: string

Company name

Encrypted: string

RSA encrypted password and timestamp

Name: string

Full name of registrant

Phone: string

Phone number with country code and + in front

Example
{
  "ApiKey": "hzYAVO9Sg98nsNh81M84O2kyXVy6K1xwHD8",
  "ChResp": "ezwXceQ63fV9oWTSJBAE2Zq1Cw5tBIJe+7+Rl8jrgbk=|1475429754114|4017bda8-0a15-4154-a8b7-88069b05cb4e",
  "Company": "ISECure Oy",
  "Encrypted": "...",
  "Name": "Dan Forsberg",
  "Phone": "+358404835507"
}

RegisterResp: object

ApiKey: string

Integrator API Key

ResponseCode: string

Two digit response code in string format

ResponseText: string

Human readable response text

Example
{
  "ApiKey": "4vN6hGHrav31smM0Ha1k15MDlZKOEGn43UToWTt2",
  "ResponseCode": "..",
  "ResponseText": ".."
}

Response: object

ResponseCode: string

Two digit response code in string format

ResponseText: string

Human readable response text

Example
{
  "ResponseCode": "string",
  "ResponseText": "string"
}

ShareCertsResp: object

ResponseCode: string

Two digit response code in string format

ResponseText: string

Human readable response text

SharedFrom: string[]

ExtEmail account that this account shares certs from

string
SharedTo: string[]

ExtEmail account that this account shares certs for

string
Example
{
  "ResponseCode": "..",
  "ResponseText": "..",
  "SharedFrom": "string",
  "SharedTo": "string"
}

UnshareCertsResp: object

ResponseCode: string

Two digit response code in string format

ResponseText: string

Human readable response text

SharedFrom: string[]

ExtEmail account that this account shares certs from

string
SharedTo: string[]

ExtEmail account that this account shares certs for

string
Example
{
  "ResponseCode": "..",
  "ResponseText": "..",
  "SharedFrom": "string",
  "SharedTo": "string"
}

UploadFileReq: object

FileContents: string

Base64 encoded file contents

FileName: string

Upload file name

FileType: string

Bank specific file type

Signature: string

Detached PGP signature(s) made with registered PGP key(s)

Example
{
  "FileContents": "...",
  "FileName": "testfile",
  "FileType": "KTL",
  "Signature": "string"
}

UploadKeyReq: object

PgpKey: string

ASCII armored PGP Key

PgpKeyPurpose: string

PGP key purpose, i.e. export (exporting cert private key) or authorize (upload content authorization verification).

Example
{
  "PgpKey": "...",
  "PgpKeyPurpose": "authorize"
}

VerifyEmailReq: object

AccessToken: string

Access token from login response

Code: string

Code from email

Example
{
  "AccessToken": "eyJraWQiO...CzzcdcdAdEzKIcJPR7Fda0A",
  "Code": "123456"
}

VerifyPhoneReq: object

Code: string

Code from SMS

Example
{
  "Code": "123456"
}
Documentation by Spectacle