Use of Suomi.fi Authorization in Vero API Interfaces

The interface user must request the Suomi.fi authorization with the GetToken interface before making calls to other Vero API interfaces that require a Suomi.fi authorization. The GetToken interface returns the authorization token for the user.

• The authorization token is a technical signed data structure that contains the Suomi.fi authorizations which have been granted for the interface user. The technical data structure is implemented according to the JSON Web Token model. An authorization token gives the access to act on behalf of another organization for 60 minutes from the moment the token is created.

Authorization token

Suomi.fi authorization tokens are retrieved for each customer for whom the user is acting on behalf within the next hour. The tokens are created with a single Vero API GetToken interface call. The authorization tokens are returned in the response message for each customer who have granted the user Suomi.fi authorizations. The customer-specific authorization token is placed into Vero API call’s header called Vero-authorizationtoken. The use of authorization token speeds up the response times in Vero APIs by 300 – 500 ms per call and reduces the network load to DVV. Using the Vero API GetToken interface the user’s software can verify the authorizations validity before calling other interfaces.

Suomi.fi authorization token is mandatory in all Vero API interfaces which require authorizations when acting on behalf of another organizations. The authorization token will replace the current procedure where authorizations are verified directly from the Digital and population data services agency (DVV) during each API call.

Authorization token is not mandatory to use in interfaces which do not require Suomi.fi authorizations. This change also doesn’t affect situations where users are managing their own data in interface calls. If an interface requires a Suomi.fi authorization, it is informed in the interface’s documentation. The documentation can be found in Vero API portal. 

Suomi.fi authorizations are required in the following Vero API interfaces currently:

• Decision and letters interfaces
• Role registration update
• Line of Business and Accounting Period Query
• Tax period inquiry
• Balance specification
• Transaction search
• Car tax decision interfaces and return status inquiry
• EMCS interfaces
• Excise duties
• Household expenses reporting interfaces
• Pensions and benefits reporting and Pensions and benefits changed withholding data inquiry
• Value added tax and VAT EC sales interfaces
• Corporate income tax interfaces (prepayment interfaces, send profit distribution, share values inquiry)