All API requests are made over HTTPS.
Some APIs (e.g. PSD2 APIs) require the use of mutually authenticated TLS. TLS version 1.2 is strongly recommended over all previous versions.
Additional Security measures and requirements for authentication and authorization depend on the API and the type of data being processed. Confidential data must be protected both in transit and in store. Detailed requirements vary case-by-case and will be explained in API documentation.
The table below describes our general principles for API security.
|Security level||Access Control Requirements|
|High||The client app must be authenticated and authorized to use the API. Strong customer authentication (SCA) using OIDC flow is required. Further requirements include (but are not limited to) mutually authenticated TLS and data encryption.|
|Substantial||The client app must be authenticated and authorized to use the API. Strong customer authentication and end-user authorization are usually required.|
|Basic||The client app must be registered and will be authenticated prior to granting access to the API. A user can be a technical user, e.g. a system or a process, and it must be authorized to use the API. Usually, there is no need to authenticate the end-user, though the user information can be relayed in the payload.|
|Open||The client application must be registered.|
Our APIs use authentication and authorization methods based on Oauth 2.0 and OpenID Connect.
In sandbox, most of our APIs also support static tokens for simulating authorization. Static tokens can be used in the x-authorization or Authorization header, depending on the API.
The following static tokens are available for use:
Each API bears a version number in its uri, e.g. sandbox.apis.op-palvelut.fi/v1/accounts. Major versions of each API are not compatible. However, minor updates and version bumps will retain backwards compatibility; these will not be reflected in the URI.
After the publishing of a new version of an API, older versions will be deprecated. Once deprecated, the API will no longer be developed aside from important bug fixes. We encourage users to migrate to newer versions once an API is marked as deprecated.
The following headers are recommended for each request:
|x-api-key||a161-43ee-b222||(Required) API key of the client app|
|x-session-id||c38a-11e7-abc4||(Optional) Session identifier for in-memory data|
|x-request-id||string||(Optional) Unique ID for the request (not validated at the moment)|
|x-authorization / Authorization||see authentication||(Required) Authorization token|
Currently, all sandbox APIs have a limit of 1000 requests / day for each application. If you exceed the daily limit, the server responds with HTTP status code 429 and three headers: X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset. Of these, the latter describes the period of time after which the rate limit will be reset.
If you feel that 1000 requests per day isn't enough, please contact us at firstname.lastname@example.org and tell us about your needs.
Successful operations are indicated by HTTP status codes in the range 200-399.
Below is a list of the most common HTTP status codes.
|200||OK||The has been completed successfully.|
|201||CREATED||The resource has been successfully create.|
|400||BAD REQUEST||Some headers, parameters, or payload contents are missing or invalid. Retrying the same request again will not succeed.|
|401||UNAUTHORIZED||Invalid or missing authentication/authorization.|
|403||FORBIDDEN||The authenticated/authorized user or application does not have access rights to the requested.|
|429||TOO MANY REQUESTS||The client application has exceeded its rate limit. The application must wait until the limit expires.|
|500||INTERNAL SERVER ERROR||A system error prevented the operation from being completed.|
|503||SERVICE UNAVAILABLE||The service is temporarily unavailable due to e.g. overload or maintenance.|
Occasionally, API calls fail. In these cases, the error type is indicated by an HTTP status code, and a further error description will be provided in the error payload.
Authorization flows are a notable exception: in some cases, providing accurate error descriptors is considered unsafe and only a general error page will be returned.
The following table describes the contents of a typical error payload:
|Id||yes||A unique identifier for the error.|
|Level||yes||Error level: FATAL, ERROR or WARN. For a FATAL, no retry is likely to succeed without server side maintenance measures. An ERROR may be temporary and the request may be retried later. A WARN level error indicates that some part of the execution of the operation went wrong, but that the operation was nonetheless successful.|
|Type||yes||Errors are of type SECURITY, VALIDATION, TECHNICAL and BUSINESS. Errors of type BUSINESS will be accompanied by a business specific error code and an optional detailed error code.|
|Message||yes||A human-readable description of the error condition.|
|Code||no||An error code defined by the application, for errors of type BUSINESS only.|
|DetailedConstraitViolations||no||A map of validation fields and constraints that failed, for errors of type VALIDATION only.|
Below is a sample error payload.
"message": "Account balance exceeded",