Transferring Web API session
In the selection interface, the user selects parties on whose behalf they are acting. The session transfer feature is intended to transfer these selections from one e-service to another. This way, the user does not have to re-select the party on whose behalf they are acting when switching from one e-service to another. The transfer is available for HPA and YPA Web API sessions.
Performing the transfer
- When acting behalf of another person, the session transfer is performed as follows. The call parameters with variable values are described in the table below the example call.
- The e-service starts the session by calling the registration API, directing the user to select a person on whose behalf they are acting and then replacing the temporary identifier with OAuth access token. The e-service that started the session requests a transfer identifier from the authorization service by calling the API that initiates the transfer:
GET /service/hpa/user/transfer/token/{sessionId}Parameter name | Parameter location | Parameter value |
|---|---|---|
sessionId | URL parameter | Session identifier returned from the initial registration. |
X-AsiointivaltuudetAuthorization | Header | Checksum. |
3. The returned transfer identifier (transferToken) is forwarded to the other e-service, which performs its own registration using the received transfer token:
GET /service/hpa/user/register/transfer/{transferToken}/{clientId}/{delegateId}=requestId={requestId}Parameter name | Parameter location | Parameter value |
|---|---|---|
transferToken | URL parameter | Transfer identifier returned by the Web API to the first e-service. |
clientId | URL parameter | User ID of the other e-service. |
delegateId | URL parameter | User ID of the assignee. Same for both services. |
requestId | URL parameter | Unique identifier of the request. E.g. UUID. |
X-AsiointivaltuudetAuthorization | Header | Checksum. |
4. The user is redirected to the authorize address, from which they are returned directly to the return address of the service without selecting a person to act on behalf of:
GET /oauth/authorize?client_id={clientId}&response_type=code&requestId={requestId}&user={user}&scope=read&state={state}&redirect_uri={redirectUri}&lang={lang}Parameter name | Parameter location | Parameter value |
|---|---|---|
clientId | URL parameter | User ID of the other e-service. |
requestId | URL parameter | Unique identifier of the request. E.g. UUID. |
user | URL parameter | Identifier returned from the registration (userId). |
state | URL parameter | Internal e-service identifier for the transaction. E.g. UUID. |
redirect_uri | URL parameter | E-service address to which the user is directed after the transfer. |
lang | URL parameter | User interface language as an optional parameter: fi, sv or en. |
5. The e-service once again replaces the temporary identifier received on return with OAuth access token:
POST /oauth/token?grant_type=authorization_code&redirect_uri={redirectUri}&code={code}Parameter name | Parameter location | Parameter value |
|---|---|---|
redirectUri | URL parameter | Address previously forwarded in the redirection to which the user just returned. |
code | URL parameter | Code forwarded to the e-service after the redirection (authorization_code). |
Authorization | Header | User ID and password. |
6. The assignor selected through the original e-service has now been selected also in the other e-service.
The transfer can be performed in the same way when acting on behalf of a company.
Things to consider
When transferring a session, please consider the following:
- Sessions are initialised using the same assignee identifier, i.e. the assignee must have logged in to both e-service using strong identification.
- The assignee's right to act on behalf of the other party must be re-checked after the transfer.
- The settings of the e-services must be similar enough so that the right to act can be checked after the transfer.
- All pre-selected companies on whose behalf the user is acting must return to the corresponding group also under the rules of the other e-service. This ensures that the transfer is not interrupted in the selection interface.
- If foreign person or foreign company identifiers are used, they should be in the settings and available for processing in both e-services.
- Transferring selections does not change the original session.
- The transfer must be completed before the original session is closed using the unregister call.
- The transfer identifier is valid for one minute. If the transfer identifier expires before registration, the user is presented with a role selection in connection with the redirection.