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
X-Api-Key
Integrator specific API Key. For all integrator customers, the API key must be the same.
Account
InitRegister
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 address as the account username, e.g. dan.forsberg@isecure.fi
Administer account with admin
mode, exchange files with data
mode
Operation succesfully processed. See response.
Request validation error
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"
}
VerifyEmail
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.
Account parameters
Email address as the account username, e.g. dan.forsberg@isecure.fi
Administer account with admin
mode, exchange files with data
mode
Request Content-Types: application/json
Request Example
{
"AccessToken": "eyJraWQiO...CzzcdcdAdEzKIcJPR7Fda0A",
"Code": "123456"
}
Operation succesfully processed. See response.
Request validation error
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"
}
Register
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
.
Account parameters
Email address as the account username, e.g. dan.forsberg@isecure.fi
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"
}
Operation succesfully processed. Resource created. See response.
Request validation error
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"
}
InitPasswordReset
Start password reset by getting confirmation SMS code.
Email address as the account username, e.g. dan.forsberg@isecure.fi
Administer account with admin
mode, exchange files with data
mode
Operation succesfully processed. See response.
Request validation error
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"
}
PasswordReset
Set new password for user with Email. Provide received SMS Code.
NOTE: the password must be encrypted, see Register for more details.
Account parameters
Email address as the account username, e.g. dan.forsberg@isecure.fi
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": "..."
}
Operation succesfully processed. See response.
Request validation error
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"
}
VerifyPhone
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.
Account parameters
Email address as the account username, e.g. dan.forsberg@isecure.fi
Administer account with admin
mode, exchange files with data
mode
Phone number with country code, e.g. +358401234567
Request Content-Types: application/json
Request Example
{
"Code": "123456"
}
Operation succesfully processed. See response.
Request validation error
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
ListCerts
List certs from all banks
Use
IdToken from the Login response as the Authorization
header
Use
ApiKey from the Login response as the x-api-key
header
Operation succesfully processed. See response.
Request validation error
Unauthorized
Unauthenticated
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"
}
ConfigCerts
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).
Certs handling settings
Use
IdToken from the Login response as the Authorization
header
Use
ApiKey from the Login response as the x-api-key
header
Request Content-Types: application/json
Request Example
{
"Export": "disabled"
}
Operation succesfully processed. See response.
Request validation error
Unauthorized
Unauthenticated
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"
}
ExportCert
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.
Use
IdToken from the Login response as the Authorization
header
Use
ApiKey from the Login response as the x-api-key
header
Bank used for this operation, can have values of nordea
, osuuspankki
, danskebank
, aktia
, sp
, shb
, pop
, spankki
, or alandsbanken
.
Short version of a PGP Key id idenfiying the exported Private Key, e.g. 3A3A59B2
Operation succesfully processed. See response.
Request validation error
Unauthorized
Unauthenticated
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"
}
EnrollCert
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.
Certs parameters
Use
IdToken from the Login response as the Authorization
header
Use
ApiKey from the Login response as the x-api-key
header
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": "..."
}
Operation succesfully processed. Resource created. See response.
Request validation error
Unauthorized
Unauthenticated
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"
}
ImportCert
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.
Certs parameters
Use
IdToken from the Login response as the Authorization
header
Use
ApiKey from the Login response as the x-api-key
header
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": "..."
}
Operation succesfully processed. Resource created. See response.
Request validation error
Unauthorized
Unauthenticated
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"
}
Files
ListFiles
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
Use
IdToken from the Login response as the Authorization
header
Use
ApiKey from the Login response as the x-api-key
header
Bank used for this operation, can have values of nordea
, osuuspankki
, danskebank
, aktia
, sp
, shb
, pop
, spankki
, alandsbanken
or SEB
.
Status of the
file, e.g. ALL
. NEW
, DLD
Bank specific FileType identifies the file type to be listed
Operation succesfully processed. See response.
Request validation error
Unauthorized
Unauthenticated
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"
}
UploadFile
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
Files parameters
Use
IdToken from the Login response as the Authorization
header
Use
ApiKey from the Login response as the x-api-key
header
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"
}
Operation succesfully processed. Resource created. See response.
Request validation error
Unauthorized
Unauthenticated
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"
}
DeleteFile
Deletes file on bank side. File is identified with filereference.
Use
IdToken from the Login response as the Authorization
header
Use
ApiKey from the Login response as the x-api-key
header
Bank used for this operation, can have values of nordea
, osuuspankki
, danskebank
, aktia
, sp
, shb
, pop
, spankki
, alandsbanken
or SEB
.
File reference id from list files
File reference id from list files
Operation succesfully processed. See response.
Request validation error
Unauthorized
Unauthenticated
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"
}
DownloadFile
Downloads file identified with filereference, filetype, and bank. Filereference is received in file list from bank. Returns base64 encoded file content.
Use
IdToken from the Login response as the Authorization
header
Use
ApiKey from the Login response as the x-api-key
header
Bank used for this operation, can have values of nordea
, osuuspankki
, danskebank
, aktia
, sp
, shb
, pop
, spankki
, alandsbanken
or SEB
.
File type from list files
File reference identifier from list files
Operation succesfully processed. See response.
Request validation error
Unauthorized
Unauthenticated
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"
}
Integrator
ListAccounts
List accounts registered under the integrator's API key. Account that created the API key is authorized to call this.
Use
IdToken from the Login response as the Authorization
header
Use
ApiKey from the Login response as the x-api-key
header
Operation succesfully processed. See response.
Request validation error
Unauthorized
Unauthenticated
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"
}
Pgp
DeleteKey
Delete PGP key.
Pgp parameters
Use
IdToken from the Login response as the Authorization
header
Use
ApiKey from the Login response as the x-api-key
header
Request Example
{
"PgpKeyId": "DBCBE671"
}
Operation succesfully processed. See response.
Request validation error
Unauthorized
Unauthenticated
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"
}
ListKeys
List PGP keys.
Use
IdToken from the Login response as the Authorization
header
Use
ApiKey from the Login response as the x-api-key
header
Operation succesfully processed. See response.
Request validation error
Unauthorized
Unauthenticated
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"
}
UploadKey
Upload PGP key.
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.
Use
IdToken from the Login response as the Authorization
header
Use
ApiKey from the Login response as the x-api-key
header
Request Content-Types: application/json
Request Example
{
"PgpKey": "...",
"PgpKeyPurpose": "authorize"
}
Operation succesfully processed. Resource created. See response.
Request validation error
Unauthorized
Unauthenticated
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"
}
Session
Logout
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.
Use
IdToken from the Login response as the Authorization
header
Use
ApiKey from the Login response as the x-api-key
header
Email address as the account username, e.g. dan.forsberg@isecure.fi
Administer account with admin
mode, exchange files with data
mode
Operation succesfully processed. See response.
Request validation error
Unauthorized
Unauthenticated
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"
}
InitLogin
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 address as the account username, e.g. dan.forsberg@isecure.fi
Administer account with admin
mode, exchange files with data
mode
Operation succesfully processed. See response.
Request validation error
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"
}
Login
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
Login body parameters
Email address as the account username, e.g. dan.forsberg@isecure.fi
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": "..."
}
Operation succesfully processed. See response.
Request validation error
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"
}
LoginMFA
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.
Session parameters
Email address as the account username, e.g. dan.forsberg@isecure.fi
Administer account with admin
mode, exchange files with data
mode
Request Content-Types: application/json
Request Example
{
"Code": "123456",
"Session": "..."
}
Operation succesfully processed. See response.
Request validation error
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
-
Not present on MFA login initiation, i.e.
- ApiKey: string
-
Integrator API Key
-
Not present on MFA login initiation, i.e.
admin
mode)
-
Not present on MFA login initiation, i.e.
- ExpiresIn: string
-
Session expiration time
-
Not present on MFA login initiation, i.e.
admin
mode)
-
Not present on MFA login initiation, i.e.
- IdToken: string
-
ID token
-
Not present on MFA login initiation, i.e.
admin
mode
-
Not present on MFA login initiation, i.e.
- 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)
-
Only present on MFA login initiation, i.e.
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"
}
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) orauthorize
(upload content authorization verification).
Example
{
"PgpKey": "...",
"PgpKeyPurpose": "authorize"
}