Service provider’s integration guide
This page provides guidance on implementing integration when redirecting customers from a service provider’s service to the authorization request acceptance process in the Datahub Authorization Service (Use case 2).
Stage 1: Registering a return URL
The return URL must meet the following requirements:
Contains domain and path only (no query parameters or fragment identifiers)
HTTPS required in production environment / HTTP permitted in test environment
Examples of permitted return URLs:
https://sahkopalvelu.fi/authorization/callback
https://api.sahkopalvelu.fi/dhvp/return
https://sahkopalvelu.fi/services/dhvp
Examples of prohibited return URLs:
https://sahkopalvelu.fi/callback?service=dhvp: Includes query parameters
https://sahkopalvelu.fi/callback#result: Includes a fragment identifier
https://sahkopalvelu.fi/callback?: Includes a search parameter
http://sahkopalvelu.fi/callback: HTTP not permitted (production)
Stage 2: Redirecting the user to the Authorization Service
Creating the URL:
https://{dhvp-ympäristö}/{lang}/{requestId}?returnUrl={returnUrl}&relay={relay} URL parameters:
Parameter | Type | Required | Description |
|---|---|---|---|
lang | String | Yes | UI language. Must be one of the following: FI, SV, EN. |
requestId | UUID v4 | Yes | The external ID (ExternalAuthorizationRequestID) of the authorization request (DH-83X) created in the background and to be accepted by the user. |
Query parameters:
Parameter | Type | Required | Description |
|---|---|---|---|
returnUrl | URL string | Yes | Registered return URL |
relay | Base64 string | No | Optional relay state data (max. 62 characters, base64-encoded) |
Example:
https://dhvp.fingrid.fi/fi/550e8400-e29b-41d4-a716-446655440000?returnUrl=https%3A%2F%2Fsahkopalvelu.fi%2Fcallback&relay=c29tZV9zdGF0ZV9kYXRh Stage 3: Redirecting the user from the Authorization Service to a given return URL
When a user completes (or cancels) the authorization process, the Datahub Authorization Service redirects them back to the given return URL.
Return URL parameters
The Datahub Authorization Service adds the following query parameters to the return URL:
Parameter | Type | Description |
|---|---|---|
requestId | UUID v4 | The same requestId as supplied during redirect. |
relay | Base64 string | relay state data (only if supplied during redirect) |
status | String | In accordance with the user’s action on the request: accept, reject. If an error occurs or if the user cancels the process, the value is empty. |
lang | String | Same as the UI language supplied during redirect: FI, SV or EN. |
Example without relay parameter:
https://sahkopalvelu.fi/callback?requestId=550e8400-e29b-41d4-a716-446655440000&status=accept&lang=fi Example with relay parameter:
https://sahkopalvelu.fi/callback?requestId=550e8400-e29b-41d4-a716-446655440000&relay=c29tZV9zdGF0ZV9kYXRh&status=accept&lang=fi