1) Register on OP Developer

Sign up to access our sandbox APIs.

Note that OP Identity Service Broker does not require registering on OP Developer.

2) Test APIs in sandbox

Sandbox is the place where you can get to know our APIs. It provides the same APIs as our production environment but with mock data.

In addition, our sandbox hosts APIs that have not yet entered production (marked as "in development"). We do this so you can get to know them ahead of time, and voice your opinion on what they should look like in production.

The requirements for using an API in sandbox depend on the API in question. Check the detailed instructions in the API's documentation.

All our sandbox APIs are available free of charge for all registered developers although some restrictions on the number of calls apply.

3) Request production access

Once you've tested your application and business case in sandbox, and feel confident that our APIs fulfil your needs, it’s time to move on to production.

Different APIs have different requirements for consumers, so the time it takes to approve production keys varies by API product. In addition, some APIs pose additional requirements for production access, such as appropriate licenses, or a suitable business case. Each application is processed on a case-by-case basis.

See detailed instructions on how to request production access in the API's documentation.

Pricing information is available for our partners and production users. Depending on the API, we use combinations of various pricing models based on revenue share, events, API calls and license fees. However, following EU regulation, PSD2 APIs are free of charge both in sandbox and in production.

Security

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.

Authentication

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:

Token
6c18c234b1b18b1d97c7043e2e41135c293d0da9
b6910384440ce06f495976f96a162e2ab1bafbb4
7a66629ddf3691a66eb6466ab7a9f610de531047
3af871a0e3ebfc46f375ff2b63d1414982bd4f76

Versioning

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.

Requests

The following headers are recommended for each request:

Name	Example	Description
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 api@op.fi and tell us about your needs.

Responses

Successful operations are indicated by HTTP status codes in the range 200-399.

Below is a list of the most common HTTP status codes.

Code	Message	Description
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.

Errors

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:

Field	Required	Description
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.

{
    "errors": [
        {
            "id": "G_-20343744:143e886a59f:-7ff9",
            "level": "ERROR",
            "type": "BUSINESS",
            "message": "Account balance exceeded",
            "code": "ACC_ERR_123"
        }
      ]
}

GitHub

We provide SDKs, example apps, and other useful code on GitHub. Read the instructions to learn how to use our JavaScript SDK.

If you find bugs, have features to suggest, or want to contribute in other ways, feel free to create an issue or pull request!

NodeJs

The following code uses the OP JS SDK to fetch a list of accounts for the example customer:

import SDK from "@op/api-sdk";

const options = {
    headers: {
        'x-api-key': 'your-api-key',
        'x-authorization': 'b6910384440ce06f495976f96a162e2ab1bafbb4'
    }
}
const client = new SDK.Client(options)

const accounts = await client.getAllAccounts();
// accounts is array of Account objects.

Curl

This sample cURL request retrieves a list of accounts using Accounts V3.0.

curl -X GET \ "https://sandbox.apis.op-palvelut.fi/accounts/v3/accounts" \
-H "x-api-key: <YOUR_APP_API_KEY>" \ 
-H "authorization: Bearer 6c18c234b1b18b1d97c7043e2e41135c293d0da9" \ 
-H "accept: application/hal+json"

Response body:

{
  "accounts": [
    {
      "accountId": "L0wWwLC8voZD8ldyxYatUg0PMy03De8tk9egONlkiGE.qkLSpsR8NZhBUb7TXgfTHQ.pp9G_SlZVouGL1ncVjj-PA",
      "identifier": "FI2350009421535899",
      "identifierScheme": "IBAN",
      "nickname": "",
      "name": "KÄYTTÖTILI",
      "balance": 0,
      "currency": "EUR",
      "servicerScheme": "BIC",
      "servicerIdentifier": "OKOYFIHH",
      "_links": {
        "self": {
          "href": "https://sandbox.apis.op-palvelut.fi/accounts/v3/accounts/L0wWwLC8voZD8ldyxYatUg0PMy03De8tk9egONlkiGE.qkLSpsR8NZhBUb7TXgfTHQ.pp9G_SlZVouGL1ncVjj-PA"
        },
        "transactions": {
          "href": "https://sandbox.apis.op-palvelut.fi/accounts/v3/accounts/L0wWwLC8voZD8ldyxYatUg0PMy03De8tk9egONlkiGE.qkLSpsR8NZhBUb7TXgfTHQ.pp9G_SlZVouGL1ncVjj-PA/transactions"
        }
      }
    },
    {...}
  ],
  "_links": {
    "self": {
      "href": "https://sandbox.apis.op-palvelut.fi/accounts/v3/accounts"
    }
  }
}

FAQ

Check Frequently asked questions for the most common questions we get.

Contact

If you need support, want to give us feedback or have any other inquiry, don't hesitate to contact us.

You can reach us either by filling this form or by emailing us at api@op.fi. We will get back to you as soon as possible.

Sign up for the OP Developer newsletter now and stay updated on our latest API product releases, piloting opportunities and other news.

You can unsubscribe anytime you want.