Three ways to use the Authorization REST API of Suomi.fi e-Authorizations
The right to act on behalf of another person can be established in an e-service even without directing the end user to the client selection interface of Suomi.fi e-Authorizations.
In the client selection interface, the agent can select on whose behalf they want to act. The e-service performs a mandate query with the personal identity code of the logged-in person and the client selected from the client selection interface. However, an e-service may already have the personal identity codes of both parties from a previous service activity, in which case the right to use the service can be verified with the Authorization REST API.
This query is different from a normal Web API query in that the query can be made at the system level without any end-user interaction. In this mandate query, the e-service relays the personal identity code of the agent and the client in the query, and the API service responds ALLOWED or DISALLOWED depending on whether the agent has the right to use the service or not. Rule engine settings allow service providers to adjust the conditions for acting on behalf of another person.
The terms of service require that the person acting on behalf of another person indicates in some way that they are doing so. In other words, the query for the right to use the service may not be run without the user’s knowledge. This does not apply to establishing the right to use a service when sending notifications.
- Authorization REST API section in the API description
- Performing a mandate enquiry to this interface service requires a separately activated Rest API key, which can be requested from the deployment team: valtuudet-kayttoonotot@dvv.fi
- This query is only available for acting on behalf of another person.
Local office services
The right to act on behalf of another person can also be checked at a local office when using services in person. In this case, the customer service representative identifies the customer with an identity card and enters the client’s and agent’s personal identity codes in the system to run a query on the right to use the service. The system informs the customer service representative whether the agent has the right to act on behalf of the client. This requires the customer service representative to have a separate user interface where they can enter the personal identity codes and run a mandate query. This is how services like pharmacies establish whether a person has the right to collect another person’s prescriptions.
Mobile application
Usability of the mobile application can be improved by using the Authorization REST API to check the right to use services after selecting a client for the first time. In this case, the user (agent) does not need to be redirected to the client selection interface if they have previously acted on the client’s behalf.
Notifications
The right to act on behalf of another party can also be checked as a system-level query without any end-user interaction if it is necessary to check the right to act on behalf of another party before a notification is automatically sent to the customer from the system.