Web API and selection interface
The Web API provides a selection interface through which you can choose the objects for acting on behalf of another party, that is, the persons related to the granting of the mandates. The Web API also offers REST query interfaces that are for queries on the right to use the service, in other words, to check that the person has the right to act on behalf of the other person.
REST / JSON interfaces, which are protected with API Key or OAuth2 + +API Key authentication, are used for calling the interface.
The e-service needs the information shown below to call Suomi.fi e-Authorizations. When registering an e-service, the Digital and Population Data Services Agency provides the organisation with a Web API Client ID, API Key and Oauth password.
- Web API Client ID: Eight-digit alphanumeric identifier
- API Key: string
- Oauth password: OAuth password
If the Web API session has expired, the API will return an HTTP 401 response.
The API Key identifier required for calling interfaces with API Key protection is relayed in the X-AsiointivaltuudetAuthorization-HTTP header. Web API Client ID, time stamp and checksum (with spaces) are given as header value. More detailed descriptions of these are given in the table below.
Field | Description |
|---|---|
Web API Client ID | Client identifier specific to each e-service. |
time stamp | The time stamp is given in ISO 8601 format, for example 1997-07-16T19:20+01:00. The API will reject calls in which the time stamp differs from NTP synchronised time by ±5 minutes. |
checksum | The checksum is calculated on the basis of the call path and time stamp (with spaces). The HMAC-SHA256 hash, the encryption key of which is the API Key, is calculated from the source material. The resulting binary hash is BASE64 encoded.
|
Verification of the function performed to calculate the checksum
Use the inputs below to ensure that the function implemented to calculate the checksum works properly. When you enter the following inputs for the function, the result should be the same as below.
Path = ”/service/hpa/user/register/ae6r5iu9/111111-1111?requestId=a1b2c3d4e5f6g7”
ClientId = ”ae6r5iu9”
ApiKey = ”5ki56df8-89b8-4815-9g04-2f8e7c90”
TimeStamp = ”2017-02-09T10:29:42.09Z”
__________________
Result:
ae6r5iu9 2017-02-09T10:29:42.09Z QPbl7lf1i6XJy5WgKwkPU6eJD164PqekipCx23yhtek=
To call interfaces with OAuth2 authentication, client_id (client identifier) and client_secret (client password) are required (see Table 3).
Information needed for calling the OAuth2 interface:
- client_id: client identifier
- client_secret: client password
Two endpoints have been defined in the OAuth2 interface, which are described as URLs (web addresses). These are described in the table below.
URL | Description |
|---|---|
{rova_host}/oauth/authorize&client_id=web-api-client&response_type=code | The URL to which the user is directed to make selections. Call parameters:
Response:
|
Example request:
GET /oauth/authorize?client_id=42bbe569&response_type=code&requestId=requestId&user=5b329323-17a4-4a38-8758-2ee5686ad4e7&state=fbd24182-016c-45ea-ae9c-630a4b00188f&redirect_uri=http://localhost:8901/hpa_web_api.html&lang=fi HTTP/1.1
Host: localhost:18102
Example response:
Example of redirecting:
http://localhost:8901/hpa_web_api.html?code=3lN85M&state=fbd24182-016c-45ea-ae9c-630a4b00188f
URL | Description |
|---|---|
POST {rova_host}/oauth/token?grant_type=authorization_code | Token URL, in which the code from the user interface can be replaced with OAuth token.
Response:
|
Example request:
POST /oauth/token?code=pvGVSH&grant_type=authorization_code&redirect_uri=http://localhost:9999/callback/hpa HTTP/1.1
Authorization: Basic NDJiYmU1Njk6YmFkYi1hYmU0LWNhZmU=
Host: localhost:18102
Connection: close
Content-Length: 0
Example response:
HTTP/1.1 200 OK
Server: Apache-Coyote/1.1
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
X-Application-Context: application:8102
Cache-Control: no-store
Pragma: no-cache
Content-Type: application/json;charset=UTF-8
Transfer-Encoding: chunked
Date: Mon, 13 Jun 2016 11:06:41 GMT
Connection: close
{”access_token”:”c77e38fe-ddb4-42c4-80bd-31ad83f3b618″,”token_type”:”bearer”,”refresh_token”:”e043c886-8048-4c54-b85b-a55a25a68891″,”expires_in”:599,”scope”:”read write trust”}
Request and end user identifiers
Requests sent to the Web API must have a request identifier (requestId). The request identifier identifies the request and allows the identification of specific events entered in the logs.
Web API session start, i.e., registration request
The table describes the service addresses and example requests and responses of REST calls used in starting a Web API session, i.e., the registration request.
Acting on behalf of a person (HPA)
GET URL: {rova_host}/service/hpa/user/register/{service_id}/{personId}?requestId={requestId}
Example request:
GET /service/hpa/user/register/42bbe569/010180-9026?requestId=requestId HTTP/1.1
X-AsiointivaltuudetAuthorization: 42bbe569 2016-06-13T11:23:34.481Z +m5GW11Zxu7taZd0XEspavunQQhIGooCCuLztjlCXSQ=
Accept: application/json;charset=UTF-8
Host: localhost:18102
Connection: keep-alive
Example response:
HTTP/1.1 200 OK
Server: Apache-Coyote/1.1
Pragma: no-cache
Expires: 0
Cache-control: no-cache, no-store, max-age=0, must-revalidate
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
Content-Security-Policy: default-src ’self’; script-src ’self’ ’unsafe-inline’; style-src ’self’ ’unsafe-inline’;
X-Application-Context: application:8102
Content-Type: application/json;charset=UTF-8
Transfer-Encoding: chunked
Date: Mon, 13 Jun 2016 11:23:34 GMT
{”sessionId”:”6539d4ae-3791-4f5c-946b-7aaeb58f7107″,”userId”:”6f920b7d-be67-4a32-b431-340e21bd9359″}
Acting on behalf of a company (YPA)
GET URL: {rova_host}/service/ypa/user/register/{service_id}/{personId}?requestId={requestId}
Example request:
GET /service/ypa/user/register/42bbe569/010180-9026?requestId=requestId HTTP/1.1
X-AsiointivaltuudetAuthorization: 42bbe569 2016-06-13T12:39:26.964Z zCPlTjoRhaQUFaTAETEU6gzN7+MWH1CDM/3cKAwG3hQ=
Accept: application/json;charset=UTF-8
Host: localhost:18102
Connection: keep-alive
Example response:
HTTP/1.1 200 OK
Server: Apache-Coyote/1.1
Pragma: no-cache
Expires: 0
Cache-control: no-cache, no-store, max-age=0, must-revalidate
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
Content-Security-Policy: default-src ’self’; script-src ’self’ ’unsafe-inline’; style-src ’self’ ’unsafe-inline’;
X-Application-Context: application:8102
Content-Type: application/json;charset=UTF-8
Transfer-Encoding: chunked
Date: Mon, 13 Jun 2016 12:39:27 GMT
{”sessionId”:”27652cd4-53c6-4f83-8ed4-ffda6a7c3d17″,”userId”:”cbaa6a42-d13a-4b12-80f9-7f488a8dbe68″}
Acting on behalf of a person (HPA), transferred
GET URL: {rova_host}/service/hpa/user/register/transfer/{transfer_token}/{service_id}/{personId}?requestId={requestId}
Example request:
GET /service/hpa/user/register/transfer/8UYQjnIY4vpU8DQVzviGDqH7Kxt9sW5W
/f5f0d662/010180-9026?requestId=requestId?requestId=requestId
HTTP/1.1
X-AsiointivaltuudetAuthorization: f5f0d662 2016-09-14T08:48:15.503Z Kt2vtNGi3FIDsTeEgAcJfqR17N+jYAOOW/XA48VEGf0=
Accept: application/json;charset=UTF-8
Host: localhost:18102
Connection: keep-alive
Example response:
HTTP/1.1 200 OK
Server: Apache-Coyote/1.1
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
Set-Cookie: JSESSIONID=5C0B947E916DF07CBC929BBFD629EF2E; Path=/; HttpOnly
X-Application-Context: application:18102
Content-Type: application/json;charset=UTF-8
Transfer-Encoding: chunked
Date: Wed, 14 Sep 2016 08:48:15 GMT64
{”sessionId”:”9a980afa-1ea5-402e-a405-d52a08e36ef1″, ”userId”:”00b1c274-97a4-48de-a1a4-c634e2928cf2″}
0
Acting on behalf of a company (YPA), transferred
GET URL: {rova_host}/service/ypa/user/register/transfer/{transfer_token}/{service_id}/{personId}?requestId={requestId}
Example request:
GET
/service/ypa/user/register/transfer/NnO6urpyH3Z1l2jbd7rrHewSGfcpxkKf
/f5f0d662/010180-9026?requestId=requestId HTTP/1.1
X-AsiointivaltuudetAuthorization: f5f0d662 2016-09-14T08:56:20.32Z gKmAJz9XpqhQFlvGcLLqTxxWaGrfbJOLdZtzgRiQRiY=
Accept: application/json;charset=UTF-8
Host: localhost:8102
Connection: keep-alive
Example response:
HTTP/1.1 200 OK
Server: Apache-Coyote/1.1
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
Set-Cookie: JSESSIONID=A54DF5C396F59B587994A71A9FBE7003; Path=/; HttpOnly
X-Application-Context: application:18102
Content-Type: application/json;charset=UTF-8
Transfer-Encoding: chunked
Date: Wed, 14 Sep 2016 08:56:20 GMT64
{”sessionId”:”faa683f0-b56e-4667-bc85-51e65a8a1ce4″,”userId”:”c4f6900a-c1f0-4a37-880b-c1d2f3470593″}
0
Note! Allowed interfaces are defined at the time of commissioning, so all offered interfaces may not be available to the client organisation.
The registration request must contain the X-AsiointivaltuudetAuthorization-header.
The fields in the response to the registration request are described below.
Response field | Description |
|---|---|
SessionId | UUID format session identifier used for additional queries. |
UserId | UUID format user-specific one-time identifier, which is relayed to the user interface. The identifier remains valid for ten minutes during which the user must be redirected to the user interface. |
Below is a description of the service addresses for REST calls and example requests and responses when acting on behalf of a person. There are three interfaces available:
- The Delegate interface is used to call for all of the assignee’s assignors, i.e. the persons on whose behalf they are entitled to act, based on the assignee’s personal identity code or other identifier.
- The Authorization interface is used to check whether the assignee has the right to manage a specific matter on behalf of the assignor.
- The AuthorizationList interface is used to check which matters the assignee has the right to act on behalf of the assignor.
Access_token is read either in the Authorization: Bearer header or in the URL parameter.
Delegate
GET URL: {rova_host}/service/hpa/api/delegate/{sessionId}?requestId={requestId}&access_token={access_token}
Example request:
GET /service/hpa/api/delegate/6539d4ae-3791-4f5c-946b-7aaeb58f7107?requestId=requestId&access_token=5b8fa683-0270-44e1-bc08-14622da02c3d HTTP/1.1
X-AsiointivaltuudetAuthorization: 42bbe569 2016-06-13T11:27:48.512Z vRd7rhcKL8Pix8PurTiV5SvC8Ian2cQY+siajTjnilU=
Host: localhost:18102
Accept: application/json;charset=UTF-8
Connection: keep-alive
Example response:
HTTP/1.1 200 OK
Server: Apache-Coyote/1.1
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
X-Application-Context: application:8102
Content-Type: application/json;charset=UTF-8
Transfer-Encoding: chunked
Date: Mon, 13 Jun 2016 11:27:48 GMT
[{"personId":"310813A951F","name":"Kumpulainen Onni Matias"}]
Authorization
GET URL: {rova_host}/service/hpa/api/authorization/{sessionId}/{personId}?requestId={requestId}&issues={issues}&access_token={access_token}
The URI for which authorisation is requested is used as the value of the Issues parameter. This parameter is not mandatory. There can be several parameters. The URI specified in the parameter may contain specifiers defined as query parameters. If specifiers are used in the URI, their keys and values should be represented in a URL-encoded format.
Example request:
GET /service/hpa/api/authorization/7407df88-8fbe-4e16-94fd-05467963b49e/120508A950F?requestId=testClientRequestId&issues=http%3A%2F%2Fvaltuusrekisteri.suomi.fi%2Fpalkkatietojen_ilmoittaminen%3FprincipalId%3D120508A950F%26subOrganization%3D134567-1 HTTP/1.1
X-AsiointivaltuudetAuthorization: 42bbe569 2016-06-13T11:48:02.087Z vFxeTk/6oJlqHxhkE3YTyuTQh7X2SMrB/XhvAvemIuQ=
Host: localhost:18102
Accept: application/json;charset=UTF-8
Connection: keep-alive
Example response:
X-AsiointivaltuudetAuthorization: 42bbe569 2016-06-13T11:48:02.087Z vFxeTk/6oJlqHxhkE3YTyuTQh7X2SMrB/XhvAvemIuQ=
Host: localhost:18102
Accept: application/json;charset=UTF-8
Connection: keep-alive HTTP/1.1 200 OK
Server: Apache-Coyote/1.1
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
X-Application-Context: application:8102
Content-Type: application/json;charset=UTF-8
Transfer-Encoding: chunked
Date: Mon, 13 Jun 2016 11:48:02 GMT
[{"reasons":[],"result":"ALLOWED","principal":{"personId":"010316A998C","name":"Pekkala Esko-Olli"}}]
AuthorizationList
GET URL: {rova_host}/service/hpa/api/authorizationlist/{sessionId}/{personId}?requestId={requestId}&access_token={access_token}
Example request:
GET /service/hpa/api/authorizationlist/1bed4372-5706-4a3d-be1c-84a4c436636a/310813A951F?requestId=testClientRequestId&access_token=82e69cb5-b659-4dec-a12e-9fd9cf62db9f HTTP/1.1
X-AsiointivaltuudetAuthorization: 42bbe569 2017-10-25T05:22:03.873Z 1CngFqz1RPPSih0+4K8lsDa/e3rl79wywUP2hxkEJ6k=
Host: localhost:8102
Accept: application/json;charset=UTF-8
Connection: keep-alive
Example response:
X-AsiointivaltuudetAuthorization: 42bbe569 2017-10-25T05:22:03.873Z 1CngFqz1RPPSih0+4K8lsDa/e3rl79wywUP2hxkEJ6k=
Host: localhost:8102
Accept: application/json;charset=UTF-8
Connection: keep-alive HTTP/1.1 200
Set-Cookie: JSESSIONID=98A7D5AE47A0B927496AFC382FD5F65D;path=/;
HttpOnly X-Application-Context: roles-auths-web-api:8102
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
Content-Type: application/json;charset=UTF-8
Transfer-Encoding: chunked
Date: Wed, 25 Oct 2017 05:22:05 GMT
[{"reasons":[],"roles":["ALL"],"principal":{"personId":"010316A998C","name":"Pekkala Esko-Olli"}}]
Delegate
The Delegate interface is used to retrieve a list of assignors, i.e., the persons on whose behalf the assignee is authorised to act.
The sessionId received as response to the registration request is relayed in the REST call.
The table describes the elements of the Delegate response message.
Element name | Type | Description | Domain |
|---|---|---|---|
principals | array<Principal> | a list of basic data on assignors | list n*[principal [personId,name]] or empty list |
The table describes the Principal element that contains the elements personId and name.
Element name | Type | Description |
|---|---|---|
personId | string | personal identity code or UID |
name | string | name |
Domain: The name consists of the person’s last name and first names, which are separated by a space by default. The separator between the last name and the first names can be changed for each service.
The separator is limited to two characters and can contain any of the following characters: “ ,\-.:;_”. First names are always separated by a space. Names are provided if available.
Authorization
The Authorization interface is used to check whether the assignee has the right to manage a specific matter on behalf of the assignor.
The sessionId received as response to the registration request, the personId of the target for service authorisation verification and the authorisation of which matter is verified are relayed in the REST call.
The Authorization response states whether the assignee has the right to act on behalf of the selected assignor. The right to act on behalf of the assignor is given in the authorization field and the favourable decision (ALLOWED) or negative decision (DISALLOWED) is returned as authorisation value. If the decision is DISALLOWED and the service is permitted to show the grounds for the rejection, they are returned in the reason fields of the list.
The table shows a response message to a successful Authorization query.
Element name | Type | Description | Domain |
|---|---|---|---|
result | string | Information on whether the assignee has the right to act on behalf of the assignor in the matter in question. | ALLOWED or DISALLOWED |
reasons | array<DecisionReason> | Value is conditional. There may be more than one element, one for each rejection ground. Use is separately agreed on in the service contract. | n* reason[rule, value] |
The table describes the DecisionReason element, which contains the elements reasonRule, reasonValue and valueType.
Element name | Type | Description | Domain |
|---|---|---|---|
reasonRule | string | identifier of the rule in question | |
reasonValue | string | reason localisation key | |
valueType | string | DESCRIPTION, EXCEPTION |
AuthorizationList
The AuthorizationList interface is used to check which matters the assignee has the right to act on behalf of the assignor.
The sessionId received as response to the registration request, the personId of the target for service authorisation verification are relayed in the REST call.
The AuthorizationList response gives a list of matters where the assignee has the right to act on behalf of the assignor. The right to act on behalf of a client is indicated in the roles field, the value of which is either ALL (unlimited right to act on behalf of the client), joint custody code or notification‑rights code or a list of matters (issue URI) that the right to act on behalf of the client applies to. The response may have more than one service role. An empty list means that there is no authorisation.
The table shows a response message to a successful AuthorizationList query.
Element name | Type | Description | Domain |
|---|---|---|---|
roles | array<String> | List of the assignee’s rights to act on behalf of the assignor. If the authority has been obtained through a mandate to represent, the mandate theme can be accompanied by the business ID of the company to be represented in the URI fragment section, if this has been specified in the service-specific configuration. If a response features specifiers in the URI of a mandate theme, the keys and values of the specifiers are displayed in a URL-encoded format. If competence has been established in the context of joint custody, and the configuration parameter “032.001.4.2 The individual must possess a joint custody code” is enabled, the custody‑sharing or notification‑rights code is applied as the operative role identifier. An authorisation role derived from the legal capacity of a guardian or an agent under a continuing power of attorney is returned in accordance with rule 036.010.1.4. | [n* ”issue URI”], [”ALL”] Joint custody code or notification‑rights code:
Authorization roles for a guardian or an attorney with a continuing power of attorney:
|
reasons | array<DecisionReason> | Value is conditional. There may be more than one element, one for each rejection ground. Use is separately agreed on in the service contract. | n* reason[rule, value] The attribute rule contains the identifier for the rule in question and the attribute value contains the reason localisation key. |
The table describes the DecisionReason element, which contains the elements reasonRule, reasonValue and valueType.
Element name | Type | Description | Domain |
|---|---|---|---|
reasonRule | string | identifier of the rule in question | |
reasonValue | string | reason localisation key | |
valueType | string | DESCRIPTION, EXCEPTION |
Below is a description of the service addresses for REST calls and example requests and responses when acting on behalf of a company.
The OrganizationalRoles interface is used to check whether a person has the right to act on behalf of a company and what kind of role they have in relation to the company.
Access_token is read either in the Authorization: Bearer header or in the URL parameter.
OrganizationRoles (all selected)
GET URL: {rova_host}/service/ypa/api/organizationRoles/{sessionId}?requestId={requestId}&access_token={access_token}
Example request:
GET /service/ypa/api/organizationRoles/450c59d4-0456-4ad5-b298-ac9c4b5c44e9?requestId=requestId&access_token=d8b67168-0354-4795-b7d9-fbdc4a4850ad HTTP/1.1
X-AsiointivaltuudetAuthorization: 42bbe569 2016-06-13T11:50:48.327Z ES9QTREbV0tL4N0NCr5pYs8Tfcvr9wz+1tIfLMAI+pY=
Host: localhost:18102
Accept: application/json;charset=UTF-8
Connection: keep-alive
Example response:
HTTP/1.1 200 OK
Server: Apache-Coyote/1.1
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
X-Application-Context: application:8102
Content-Type: application/json;charset=UTF-8
Transfer-Encoding: chunked
Date: Mon, 13 Jun 2016 11:50:47 GMT
[
{
"name": "Lumi Global Oy",
"identifier": "123456-1",
"complete": true,
"roles": [
"NIMKO",
"TJ",
"http://valtuusrekisteri.suomi.fi/palkkatietojen_katselu?principalId=6004971-1&subOrganization=1234",
"http://valtuusrekisteri.suomi.fi/palkkatietojen_katselu?principalId=6004971-1&subOrganization=a%26b"
]
}, {
"name": "Asunto Oy Testikatu 1",
"identifier": "7769189-0",
"complete": true,
"roles": ["PJ"]
}
]
OrganizationRoles (one)
GET URL: {rova_host}/service/ypa/api/organizationRoles/{sessionId}/{organizationId}?requestId={requestId}&access_token={access_token}
Example request:
GET /service/ypa/api/organizationRoles/450c59d4-0456-4ad5-b298-ac9c4b5c44e9/123456-1?requestId=requestId&access_token=d8b67168-0354-4795-b7d9-fbdc4a4850ad HTTP/1.1
X-AsiointivaltuudetAuthorization: 42bbe569 2016-06-13T11:50:48.327Z ES9QTREbV0tL4N0NCr5pYs8Tfcvr9wz+1tIfLMAI+pY=
Host: localhost:18102
Accept: application/json;charset=UTF-8
Connection: keep-alive
Example response:
HTTP/1.1 200 OK
Server: Apache-Coyote/1.1
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
X-Application-Context: application:8102
Content-Type: application/json;charset=UTF-8
Transfer-Encoding: chunked
Date: Mon, 13 Jun 2016 11:50:47 GMT
[
{
"name": "Lumi Global Oy",
"identifier": "123456-1",
"complete": true,
"roles": [
"NIMKO",
"TJ",
"http://valtuusrekisteri.suomi.fi/palkkatietojen_katselu?principalId=6004971-1&subOrganization=1234",
"http://valtuusrekisteri.suomi.fi/palkkatietojen_katselu?principalId=6004971-1&subOrganization=a%26b"
]
}
]
The OrganizationRoles response contains a list (organizationList) of companies associated with the assignee and their roles in them. If any of the roles remains unspecified, for example, as a result of such events as a remote procedure call time out, the organization-element complete field will have false as its value.
Element name | Description | Domain |
|---|---|---|
organizationList | list of companies | List n*[organization] or empty. May contain several elements only if the selection of multiple targets has been enabled in the e-service. |
Principal element: organization
Element name | Description | Domain |
|---|---|---|
organizationIdentifier | company identifier | business ID (VAT or national business ID) |
name | company name | name |
roles | list of roles (only used for requests that use the organisation identifier filter, or if the user is associated with only one company) | list n*[role [”NIMKO”, ”TJ”, String]] |
complete | If any of the roles remains unspecified, the complete field will have false as its value. | true (default), false |
A transfer identifier (transfer_token) can be created from the current Web API session, and it will be relayed to the next e-service.
The table describes the service addresses and example requests and responses of REST calls used in transferring a Web API session.
Acting on behalf of a person (HPA)
GET URL: {rova_host}/service/hpa/user/transfer/token/{sessionId}
Example request:
GET /service/hpa/user/transfer/token/26f6c8d7-151c-4ee5-8927-4bbe9b6a0cf4 HTTP/1.1
X-AsiointivaltuudetAuthorization: 42bbe569 2016-09-14T08:48:09.646Z +zk9r02Xhyjxw8gmdl9DRTeCfFtNcfAKtSihMGY5X70=
Host: localhost:8102
Accept: application/json;charset=UTF-8
Connection: keep-alive
Example response:
HTTP/1.1 200 OK
Server: Apache-Coyote/1.1
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
Set-Cookie: JSESSIONID=BACEFB94488E58A5120327427B4A0090; Path=/; HttpOnly
X-Application-Context: application:18102
Content-Type: application/json;charset=UTF-8
Content-Length: 32
Date: Wed, 14 Sep 2016 08:48:09 GMT
8UYQjnIY4vpU8DQVzviGDqH7Kxt9sW5W
Acting on behalf of a company (YPA)
GET URL: {rova_host}/service/ypa/user/transfer/token/{sessionId}
Example request:
GET /service/ypa/user/transfer/token/faa683f0-b56e-4667-bc85-51e65a8a1ce4 HTTP/1.1
X-AsiointivaltuudetAuthorization: f5f0d662 2016-09-14T09:14:37.313Z LRMvn3/TkDRQKE2XQj8Bqt/wzo50crEDs4pL29Js1ro=
Host: localhost:18102
Accept: application/json;charset=UTF-8
Connection: keep-alive
Example response:
HTTP/1.1 200 OK
Server: Apache-Coyote/1.1
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
Set-Cookie: JSESSIONID=16B81306E6EE869153481D689CFBB130; Path=/; HttpOnly
X-Application-Context: application:18102
Content-Type: application/json;charset=UTF-8
Content-Length: 32
Date: Wed, 14 Sep 2016 09:14:37 GMT
LWrF1SN4OE6ZaTrnolyfxf1JdFFcHT-R
The selections made by the Web API session and the user can be released through the unregister function.
The service addresses and example requests and responses of REST calls used in ending a Web API session are described below.
Acting on behalf of a person (HPA)
GET URL: {rova_host}/service/hpa/user/unregister/{sessionId}
Example request:
GET /service/hpa/user/unregister/ef2977df-605a-49b3-9960-a9bc9b61b168 HTTP/1.1
X-AsiointivaltuudetAuthorization: 42bbe569 2016-06-14T13:41:19.103Z L/qxZb9R84KJeGJMAUNpOtlfvjDWL2mZEj+IpPUxv+I=
Host: localhost:18102
Accept: application/json;charset=UTF-8
Connection: keep-alive
Example response:
HTTP/1.1 200 OK
Server: Apache-Coyote/1.1
Pragma: no-cache
Expires: 0
Cache-control: no-cache, no-store, max-age=0, must-revalidate
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
Content-Security-Policy: default-src 'self'; script-src 'self' 'unsafe-inline';
style-src 'self' 'unsafe-inline';
X-Application-Context: application:8102
Content-Type: application/json;charset=UTF-8
Transfer-Encoding: chunked
Date: Tue, 14 Jun 2016 13:41:19 GMT
true
Acting on behalf of a company (YPA)
GET URL: {rova_host}/service/ypa/user/unregister/{sessionId}
Example request:
GET /service/ypa/user/unregister/ef2977df-605a-49b3-9960-a9bc9b61b168 HTTP/1.1
X-AsiointivaltuudetAuthorization: 42bbe569 2016-06-14T13:41:19.103Z L/qxZb9R84KJeGJMAUNpOtlfvjDWL2mZEj+IpPUxv+I=
Host: localhost:18102
Accept: application/json;charset=UTF-8
Connection: keep-alive
Example response:
HTTP/1.1 200 OK
Server: Apache-Coyote/1.1
Pragma: no-cache
Expires: 0
Cache-control: no-cache, no-store, max-age=0, must-revalidate
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
Content-Security-Policy: default-src 'self'; script-src 'self' 'unsafe-inline'; style-src 'self' 'unsafe-inline';
X-Application-Context: application:8102
Content-Type: application/json;charset=UTF-8
Transfer-Encoding: chunked
Date: Tue, 14 Jun 2016 13:41:19 GMT
true
The following Web APIs also include JSON Web Token (JWT) versions:
- Authorization
- AuthorizationList
- organizationRoles (all selected).
They return the response as JSON Web Tokens as defined in the RFC 7519 standard.
A version of the OrganizationalRoles interface that returns JWTs is available. It is used to retrieve roles later instead of the default response. This makes it possible to return the topics of several authorisations in the response message.
Tokens provide additional security for data transfer. Responses to mandates for transactions, they contain signed general information specified in Table 19 and information per mandate for transactions specified in Table 20:
General information on JWT responses:
Key | Value/description |
|---|---|
iss (issuer) | 'Suomi.fi e-Authorizations' |
aud (audience) | UUID of the used service |
iat (issueTime) | time of creation |
jti (jwtID) | token UUID |
sub (subject) | 'Authorization' | 'AuthorizationList' | 'OrganizationalRoles' |
Information on JWT responses per mandate for transactions:
Key | Value/description |
|---|---|
principal | assignor’s personal identity code |
personal identity code | end user’s personal identity code |
response | interface-specific response |
issue | subject filter for the Authorization request |
When using JWT versions of interfaces, in addition to the settings required by the basic interfaces, the settings in Table 21 are required.
Like other interfaces, JWT interfaces are available in the Suomi.fi e-Authorizations service’s sample customer library roles-auths-client. In this case, the JWT client must be initialised with the UUID and the public key of the service used in addition to the standard values.
Setting | Description |
|---|---|
serviceUUID | UUID of the service to be used |
publicKey | public key of the service used to verify signature |
The following are the public keys used to verify JWT signatures in the production, QA and test environment of Suomi.fi e-Authorizations.
Production environment
MIICIjANBgkqhkiG9w0BAQEFAAOCAg8AMIICCgKCAgEAh5dSdhllRgZDvjdSayG+RUcUztSKtiPgFEmRHEW6LPesuafmKMaRQsoLgVKpJySqrkiz4dLXlm5lNJjS3GvsNLJpEVAtLjg/62+knfGxSTAuEOGw1cXgl9JXKUCF+6ROOQm4RzrgjyzJGY4shQdNnU7c7sUPEU1rWPaCwUsvxWxXq++mhrDIWaHArgqNz1vmu4exURgbmuVR4rLbrmuqlGBVKRXI9SY2SHMDlFhkpLwOP60rHw5x3atkwPvCslLGuc7c56gNhV7LxFTRzwSSCXiWC3+/nMeoJPPxlB4H6sXc3A2zfkg/AIxhjojEI1UDyCWRTYR2aAiNmfZiVVlUrGKNl8wEuW3HXTGz0/yxt9++MdLCl7a2/4QkPs3y4vgXBUC91HpFb7vO1nuJRwrcyPKtkfhvZZa8sQn/FqsJXUzcTm079xmt4vLhm5liSUik3uYDueteP3rKyUtrnXeX8VX0NoS2ROXQm7eAZskifH4cCTJU29k5/G1sgaISK/mWFEExdsI8Ua7toYOUmCh3zMc/SC0Pf+9XCPFQOpADpumb6ihoiulndDT9pyN0uXYzbblL6QC+jSZMVOEgFyhJ336BjAcd8Do86nuSTA6gtH6JsfzeKr0E+XO6QB4ayr+62guFpHxHdCV1h5B8V7x4ow2bvsHEpVRRErkNrFpkVckCAwEAAQ==Test environment
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA6/U3FlrDvNZ0ygPK1WGBjDsn0fXFgsEgNgVlY5wlp9fskVZM8efZNqxbhBYHuKUp0sAZrV7Zjj8DDk9j6XXtRRma2CKVjur1G9bm2snKfmwIjfQmdJ8iPCLLhzhsuECsNKFm0kTsc8UUWG8/zv/nWciAfF+tDXTu4K6wxW8cQjOX2u54ZqfbCL5itL/5nZk6b+Qx6eQOD0liZkEQTVZhELm4hXPhsTgIApKsN/+tnFbT7gNBsJuD+JDZBYFapFLlEz5UEjwCF+Z7WlzWy3tHxkHt+MMyJRD/gMb2zjv1W8/hs3qWrJXszW6UX6KbtQenVvfJrAeBSI2UlsE0Yx2rJwIDAQABThe table describes the service addresses and example requests and responses of REST calls that support JWT response.
Access_token is read either in the Authorization: Bearer header or in the URL parameter.
Authorization
GET URL: /api/authorization/jwt/{sessionId}/{principalId}?requestId={requestId}&issues={issues}&access_token={access_token}
Example request:
GET http://localhost:8102/service/hpa/api/authorization/jwt/ef6a5404-51b4-426e-9dc4-d4168b1ef43d/120508A950F?requestId=f4eb5a78-7db0-476a-81fd-19400b9861a5&access_token=5bc76cde-8166-4b88-b7e6-05e61645a236 HTTP/1.1
Accept: application/json;charset=UTF-8
Connection: keep-alive
Host: localhost:8102
X-AsiointivaltuudetAuthorization: 42bbe569 2018-01-24T07:14:28.431Z 2LAP79FYt/GQh9Xisc/00bobUbQWhG9Vuu0HtoXDXfs=
The URI for which authorisation is requested is used as the value of the Issues parameter. This parameter is not mandatory. There can be several parameters. The URI specified in the parameter may contain specifiers defined as query parameters. If specifiers are used in the URI, their keys and values should be represented in a URL-encoded format.
Example response:
HTTP/1.1 200
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Content-Length: 664
Content-Type: text/plain;charset=UTF-8
Date: Wed, 24 Jan 2018 07:14:29 GMT
Expires: 0
Pragma: no-cache
Set-Cookie: JSESSIONID=3D911FCD6AF0831817BF836B7A543A46;path=/;HttpOnly
X-Application-Context: roles-auths-web-api:8102
X-Content-Type-Options: nosniff
X-Frame-Options: DENY
X-XSS-Protection: 1; mode=block
eyJhbGciOiJSUzI1NiJ9.eyJwcmluY2lwYWwiOiIxMjA1MDhBOTUwRiIsImF1ZCI6ImQ0M2NmZWI0LTZiMDctNGIzNi05OGVlLWNjMWE4ZjI5YjhhNCIsInN1YiI6IkF1dGhvcml6YXRpb24iLCJyZXNwb25zZSI6IkFMTE9XRUQiLCJpc3MiOiJTdW9taS5maS1WYWx0dXVkZXQiLCJpYXQiOjE1MTY3NzgwNjksImp0aSI6ImM2YTllODBmLTI0YTgtNGQ5OS05MTBhLWI3YTdiNzk1M2FlMiIsImhldHUiOiIxMjA5NzgtOTAzOCJ9.uq1vMkVFrBpqQi8JyJHJCvqguyKpgn9o4XGBUe8nMubqMsvt5pGItBbrGFHoqjZf1jNqvPlnGvsowcyHK69VvRm9JMSVx6ldQ0aCxp2J8HvpqRIURV0XeOWU-CCP22phoeAb3dfbWen0YYAHl61_j1AlHgvrlWl3mE_E9WbMBkqysYstfGgDhsim2cvFblje8uotTb1uetyF--8FA7z9oZahgS0SokuZWB-wqAFj_5YPMLvBBdQ_yatUi5XZQpCHtJOU6H2tSZIFgOGI1Oct7qnchwAY26A6330NJger9TRqIJhHeP50IC8ir6GQPeppuN3LM7C03SyMaxIP2bRFQg
AuthorizationList
GET URL: /api/authorizationlist/jwt/{sessionId}/{principalId}?requestId={requestId}&access_token={access_token}
Example request:
GET http://localhost:8102/service/hpa/api/authorizationlist/jwt/62dce03d-8d32-4c41-b2ac-a700fc3f3064/310813A951F?requestId=728dce44-cb8e-449a-8b39-5dc6128e2b3f&access_token=1fcd01ac-ccb3-4d41-836f-2ec2d4bbc70c HTTP/1.1
Accept: application/json;charset=UTF-8
Connection: keep-alive
Host: localhost:8102
X-AsiointivaltuudetAuthorization: 42bbe569 2018-01-24T07:16:46.666Z
Example response:
HTTP/1.1 200
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Content-Length: 672
Content-Type: text/plain;charset=UTF-8
Date: Wed, 24 Jan 2018 07:16:46 GMT
Expires: 0
Pragma: no-cache
Set-Cookie: JSESSIONID=5331B72B3886AEF9F619B6890F9C586B;path=/;HttpOnly
X-Application-Context: roles-auths-web-api:8102
X-Content-Type-Options: nosniff
X-Frame-Options: DENY
X-XSS-Protection: 1; mode=block
eyJhbGciOiJSUzI1NiJ9.eyJwcmluY2lwYWwiOiIzMTA4MTNBOTUxRiIsImF1ZCI6ImQ0M2NmZWI0LTZiMDctNGIzNi05OGVlLWNjMWE4ZjI5YjhhNCIsInN1YiI6IkF1dGhvcml6YXRpb25MaXN0IiwicmVzcG9uc2UiOiJbXCJBTExcIl0iLCJpc3MiOiJTdW9taS5maS1WYWx0dXVkZXQiLCJpYXQiOjE1MTY3NzgyMDYsImp0aSI6IjYwYjFjZjJiLTdiMjctNGUxYS05MjNkLWUzM2FlNzhkNzBjYyIsImhldHUiOiIxMjA5NzgtOTAzOCJ9.V9JROf9ZsCDtXVr4Mrs1Z2c9P2h4WcQ8kKvVRgWNhBpThcute8pZbHZNf4jeVt57-MEsuTVf9Hz-eYBGbdMeH8qwzF_vo4flp687b6Y7S_PwA-2M01i4rwqWKrVl9Ed37q-PdLuYY7KobDtvQuFa7NPRuQiAFqhsQXPBY7D6szKQSWP8wlga8CijwSQCVdoUFnr0wVM8mHNq2n60VHFGua1qmlohrsLz0ZDNVSe6xSyO1TEXWYkHAQJB5aWM68Z7Qk722uOaJiDRUCI14M79vrg4zb1lGz47ZhXjQPDtvrOkdmmDutz4TfeyOy-OpGcsQDU1927Ew1YExQ1UiKM4dw
organizationRoles (all selected)
GET URL: /api/organizationRoles/jwt/{sessionId}?requestId={requestId}&access_token={access_token}
Example request:
GET http://localhost:8102/service/ypa/api/organizationRoles/jwt/2153985a-c294-4132-93a6-bffe7f76f9ef?requestId=66d05035-0805-4d40-b4af-34e5ffc5555c&access_token=4ed4d490-1c59-4888-91ea-51b545575588 HTTP/1.1
Accept: application/json;charset=UTF-8
Connection: keep-alive
Host: localhost:8102
X-AsiointivaltuudetAuthorization: 42bbe569 2018-01-24T07:21:24.13Z 7jKRE0evwaQBKhn7+DVZOv4OWEsxge4sQyZ9ffIqY6k=
Example response:
HTTP/1.1 200
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Content-Length: 771
Content-Type: text/plain;charset=UTF-8
Date: Wed, 24 Jan 2018 07:21:24 GMT
Expires: 0
Pragma: no-cache
Set-Cookie: JSESSIONID=FFDD91375F5AE5EC4A5748286897C5FC;path=/;HttpOnly
X-Application-Context: roles-auths-web-api:8102
X-Content-Type-Options: nosniff
X-Frame-Options: DENY
X-XSS-Protection: 1; mode=block
eyJhbGciOiJSUzI1NiJ9.eyJhdWQiOiJkNDNjZmViNC02YjA3LTRiMzYtOThlZS1jYzFhOGYyOWI4YTQiLCJzdWIiOiJPcmdhbml6YXRpb25hbFJvbGVzIiwicmVzcG9uc2UiOiJbe1wibmFtZVwiOlwiTHVtaSBHbG9iYWwgT3lcIixcImlkZW50aWZpZXJcIjpcIjEyMzQ1NjctMVwiLFwiY29tcGxldGVcIjp0cnVlLFwicm9sZXNcIjpbXCJOSU1LT1wiLFwiVEpcIl19XSIsImlzcyI6IlN1b21pLmZpLVZhbHR1dWRldCIsImlhdCI6MTUxNjc3ODQ4NCwianRpIjoiNTU4YzE1MTgtMWJlMy00OGJhLWE5NDYtNTAxZTAzMDcxNDAyIiwiaGV0dSI6IjAxMDE4MC05MDI2In0.i7X37jLjbnSujrtQ3sZyu5XUcJOz7DFpXii9M5FHfeWj9cWUPcrOJwUKnO0tyXqkBltfKsghoMpKH1iu4K0tvA8gm_HSG4cn9r_3Y7zfWsu2ulYwJ57IvKadqB1HMhCoWhpE2wt0DHmMTu88sVlvWRcfl3bt2K92xwquz3IJnQTiTpTNOtkOcevag7UWS173fY0fex1YFbIkan3tXOn_mbKw4KghM8m614n_PIUfpaJlDT__lSdqOCYeV5mq05Ekbi0esZzlkJ-mdfqnQKUX2sZtXqnwExCtcBoN1ee2cKktZmVdmRkxO3D5IC5uE4acwFW-59K7CyqfrE3lAHgQ
organizationRoles (token request to load response)
GET URL: /api/organizationRoles/session/jwt/{sessionId}?requestId={requestId}&access_token={access_token}
Example request:
GET http://localhost:8102/service/ypa/api/organizationRoles/session/jwt/a093bd1b-02a3-4b6d-b7a8-3eb1d399d468?requestId=768cee20-f53a-4098-9230-68d2086a4b88&access_token=f6d45628-f22a-4b97-89c1-a17b0fc541b2 HTTP/1.1
Accept: application/json;charset=UTF-8
Connection: keep-alive
Host: localhost:8102
X-AsiointivaltuudetAuthorization: 42bbe569 2018-01-24T07:23:46.489Z 9yD371vWVjmpgGys35vDApwOfaHUfJE+4xD0G5lwJ8g=
Example response:
HTTP/1.1 200
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Content-Length: 683
Content-Type: text/plain;charset=UTF-8
Date: Wed, 24 Jan 2018 07:23:46 GMT
Expires: 0
Pragma: no-cache
Set-Cookie: JSESSIONID=58AB381310F7EA6AFF46EF3124FE2EE3;path=/;HttpOnly
X-Application-Context: roles-auths-web-api:8102
X-Content-Type-Options: nosniff
X-Frame-Options: DENY
X-XSS-Protection: 1; mode=block
eyJhbGciOiJSUzI1NiJ9.eyJhdWQiOiJkNDNjZmViNC02YjA3LTRiMzYtOThlZS1jYzFhOGYyOWI4YTQiLCJzdWIiOiJPcmdhbml6YXRpb25hbFJvbGVzIiwiaXNzIjoiU3VvbWkuZmktVmFsdHV1ZGV0Iiwic2Vzc2lvbklkIjoiXCJhMDkzYmQxYi0wMmEzLTRiNmQtYjdhOC0zZWIxZDM5OWQ0NjhcIiIsImlhdCI6MTUxNjc3ODYyNiwianRpIjoiYTM4NmNmOTQtZWNkMS00NjMyLWI0NTYtYmZhYmI5ZGEzZmIyIiwiaGV0dSI6IjAxMDE4MC05MDI2In0.Nr3tVNxdoOa2Xnkv_W8LycR1Phz--wYeVoIalqxD4wpsMAjzvrPzHejT4IG8Hp02jomDwg1Q_LR-osJtwS2itgzoS3cT4mIXshkBH556t2INDHeSSGltkN5Biv-4pUyspOZsRDYXB9MnvldWFzGW2XEpuUZ2MjUQbQM4FETyfIJp5v1WIC97pK-V_OIISbC2lc0Kd3156x4t2NfOMbUWX3Wa9EgUjmRPe0B0Y8JLK57MR2UnQRWk1ckFkmeIUyUOPQwRvFshDhpQOdjWAv58qCSoM-LJx6r-GaI8zhuKW5djb0fS2YcaWzdZtzxIZs_2NI4jXAtvBV9CqjkN6D6ENg
organizationRoles (all roles using a token)
Example request:
GET http://localhost:8102/service/ypa/jwt/api/organizationRoles/
eyJhbGciOiJSUzI1NiJ9.eyJhdWQiOiJkNDNjZmViNC02YjA3LTRiMzYtOThlZS1jYzFhOGYyOWI4YTQiLCJzdWIiOiJPcmdhbml6YXRpb25hbFJvbGVzIiwiaXNzIjoiU3VvbWkuZmktVmFsdHV1ZGV0Iiwic2Vzc2lvbklkIjoiXCJhMDkzYmQxYi0wMmEzLTRiNmQtYjdhOC0zZWIxZDM5OWQ0NjhcIiIsImlhdCI6MTUxNjc3ODYyNiwianRpIjoiYTM4NmNmOTQtZWNkMS00NjMyLWI0NTYtYmZhYmI5ZGEzZmIyIiwiaGV0dSI6IjAxMDE4MC05MDI2In0.Nr3tVNxdoOa2Xnkv_W8LycR1Phz--wYeVoIalqxD4wpsMAjzvrPzHejT4IG8Hp02jomDwg1Q_LR-osJtwS2itgzoS3cT4mIXshkBH556t2INDHeSSGltkN5Biv-4pUyspOZsRDYXB9MnvldWFzGW2XEpuUZ2MjUQbQM4FETyfIJp5v1WIC97pK-V_OIISbC2lc0Kd3156x4t2NfOMbUWX3Wa9EgUjmRPe0B0Y8JLK57MR2UnQRWk1ckFkmeIUyUOPQwRvFshDhpQOdjWAv58qCSoM-LJx6r-GaI8zhuKW5djb0fS2YcaWzdZtzxIZs_2NI4jXAtvBV9CqjkN6D6ENg/?requestId=768cee20-f53a-4098-9230-68d2086a4b88&access_token=f6d45628-f22a-4b97-89c1-a17b0fc541b2 HTTP/1.1
Accept: application/json;charset=UTF-8
Connection: keep-alive
Host: localhost:8102
X-AsiointivaltuudetAuthorization: 42bbe569 2018-01-24T07:23:46.521Z U6Ghn/KKKk0ZGdLRVdDyjVb42j4OwFxn3a13vSnOxbs=
Contents of example responses
Authorization
JWT response:
eyJhbGciOiJSUzI1NiJ9.eyJwcmluY2lwYWwiOiIxMjA1MDhBOTUwRiIsImF1ZCI6ImQ0M2NmZWI0LTZiMDctNGIzNi05OGVlLWNjMWE4ZjI5YjhhNCIsInN1YiI6IkF1dGhvcml6YXRpb24iLCJyZXNwb25zZSI6IkFMTE9XRUQiLCJpc3MiOiJTdW9taS5maS1WYWx0dXVkZXQiLCJpYXQiOjE1MTY3NzgwNjksImp0aSI6ImM2YTllODBmLTI0YTgtNGQ5OS05MTBhLWI3YTdiNzk1M2FlMiIsImhldHUiOiIxMjA5NzgtOTAzOCJ9.uq1vMkVFrBpqQi8JyJHJCvqguyKpgn9o4XGBUe8nMubqMsvt5pGItBbrGFHoqjZf1jNqvPlnGvsowcyHK69VvRm9JMSVx6ldQ0aCxp2J8HvpqRIURV0XeOWU-CCP22phoeAb3dfbWen0YYAHl61_j1AlHgvrlWl3mE_E9WbMBkqysYstfGgDhsim2cvFblje8uotTb1uetyF--8FA7z9oZahgS0SokuZWB-wqAFj_5YPMLvBBdQ_yatUi5XZQpCHtJOU6H2tSZIFgOGI1Oct7qnchwAY26A6330NJger9TRqIJhHeP50IC8ir6GQPeppuN3LM7C03SyMaxIP2bRFQgExplanation of response contents:
{
"principal": "120508A950F",
"aud": "d43cfeb4-6b07-4b36-98ee-cc1a8f29b8a4",
"sub": "Authorization",
"response": "ALLOWED",
"iss": "Suomi.fi-Valtuudet",
"iat": 1516778069,
"jti": "c6a9e80f-24a8-4d99-910a-b7a7b7953ae2",
"hetu": "120978-9038"
AuthorizationList
JWT response:
eyJhbGciOiJSUzI1NiJ9.eyJwcmluY2lwYWwiOiIzMTA4MTNBOTUxRiIsImF1ZCI6ImQ0M2NmZWI0LTZiMDctNGIzNi05OGVlLWNjMWE4ZjI5YjhhNCIsInN1YiI6IkF1dGhvcml6YXRpb25MaXN0IiwicmVzcG9uc2UiOiJbXCJBTExcIl0iLCJpc3MiOiJTdW9taS5maS1WYWx0dXVkZXQiLCJpYXQiOjE1MTY3NzgyMDYsImp0aSI6IjYwYjFjZjJiLTdiMjctNGUxYS05MjNkLWUzM2FlNzhkNzBjYyIsImhldHUiOiIxMjA5NzgtOTAzOCJ9.V9JROf9ZsCDtXVr4Mrs1Z2c9P2h4WcQ8kKvVRgWNhBpThcute8pZbHZNf4jeVt57-MEsuTVf9Hz-eYBGbdMeH8qwzF_vo4flp687b6Y7S_PwA-2M01i4rwqWKrVl9Ed37q-PdLuYY7KobDtvQuFa7NPRuQiAFqhsQXPBY7D6szKQSWP8wlga8CijwSQCVdoUFnr0wVM8mHNq2n60VHFGua1qmlohrsLz0ZDNVSe6xSyO1TEXWYkHAQJB5aWM68Z7Qk722uOaJiDRUCI14M79vrg4zb1lGz47ZhXjQPDtvrOkdmmDutz4TfeyOy-OpGcsQDU1927Ew1YExQ1UiKM4dwExplanation of response contents:
{
"principal": "310813A951F",
"aud": "d43cfeb4-6b07-4b36-98ee-cc1a8f29b8a4",
"sub": "AuthorizationList",
"response": "[\"ALL\"]",
"iss": "Suomi.fi-Valtuudet",
"iat": 1516778206,
"jti": "60b1cf2b-7b27-4e1a-923d-e33ae78d70cc",
"hetu": "120978-9038"
}
organizationRoles (all selected)
JWT response:
eyJhbGciOiJSUzI1NiJ9.eyJhdWQiOiJkNDNjZmViNC02YjA3LTRiMzYtOThlZS1jYzFhOGYyOWI4YTQiLCJzdWIiOiJPcmdhbml6YXRpb25hbFJvbGVzIiwicmVzcG9uc2UiOiJbe1wibmFtZVwiOlwiTHVtaSBHbG9iYWwgT3lcIixcImlkZW50aWZpZXJcIjpcIjEyMzQ1NjctMVwiLFwiY29tcGxldGVcIjp0cnVlLFwicm9sZXNcIjpbXCJOSU1LT1wiLFwiVEpcIl19XSIsImlzcyI6IlN1b21pLmZpLVZhbHR1dWRldCIsImlhdCI6MTUxNjc3ODQ4NCwianRpIjoiNTU4YzE1MTgtMWJlMy00OGJhLWE5NDYtNTAxZTAzMDcxNDAyIiwiaGV0dSI6IjAxMDE4MC05MDI2In0.i7X37jLjbnSujrtQ3sZyu5XUcJOz7DFpXii9M5FHfeWj9cWUPcrOJwUKnO0tyXqkBltfKsghoMpKH1iu4K0tvA8gm_HSG4cn9r_3Y7zfWsu2ulYwJ57IvKadqB1HMhCo-nWhpE2wt0DHmMTu88sVlvWRcfl3bt2K92xwquz3IJnQTiTpTNOtkOcevag7UWS173fY0fex1YFbIkan3tXOn_mbKw4KghM8m614n_PIUfpaJlDT__lSdqOCYeV5mq05Ekbi0esZzlkJ-mdfqnQKUX2sZtXqnwExCtcBoN1ee2cKktZmVdmRkxO3D5IC5uE4acwFW-59K7CyqfrE3lAHgQExplanation of response contents:
{
"aud": "d43cfeb4-6b07-4b36-98ee-cc1a8f29b8a4",
"sub": "OrganizationalRoles",
"response":
"[{\"name\":\"Lumi Global Oy\",\"identifier\":\"1234567-1\"
,\"complete\":true,\"roles\":[\"NIMKO\",\"TJ\"]}]",
"iss": "Suomi.fi-Valtuudet",
"iat": 1516778484,
"jti": "558c1518-1be3-48ba-a946-501e03071402",
"hetu": "010180-9026"
}
organizationRoles (token request to load response)
JWT response:
eyJhbGciOiJSUzI1NiJ9.eyJhdWQiOiJkNDNjZmViNC02YjA3LTRiMzYtOThlZS1jYzFhOGYyOWI4YTQiLCJzdWIiOiJPcmdhbml6YXRpb25hbFJvbGVzIiwiaXNzIjoiU3VvbWkuZmktVmFsdHV1ZGV0Iiwic2Vzc2lvbklkIjoiXCJhMDkzYmQxYi0wMmEzLTRiNmQtYjdhOC0zZWIxZDM5OWQ0NjhcIiIsImlhdCI6MTUxNjc3ODYyNiwianRpIjoiYTM4NmNmOTQtZWNkMS00NjMyLWI0NTYtYmZhYmI5ZGEzZmIyIiwiaGV0dSI6IjAxMDE4MC05MDI2In0.Nr3tVNxdoOa2Xnkv_W8LycR1Phz--wYeVoIalqxD4wpsMAjzvrPzHejT4IG8Hp02jomDwg1Q_LR-osJtwS2itgzoS3cT4mIXshkBH556t2INDHeSSGltkN5Biv-4pUyspOZsRDYXB9MnvldWFzGW2XEpuUZ2MjUQbQM4FETyfIJp5v1WIC97pK-V_OIISbC2lc0Kd3156x4t2NfOMbUWX3Wa9EgUjmRPe0B0Y8JLK57MR2UnQRWk1ckFkmeIUyUOPQwRvFshDhpQOdjWAv58qCSoM-LJx6r-GaI8zhuKW5djb0fS2YcaWzdZtzxIZs_2NI4jXAtvBV9CqjkN6D6ENgExplanation of response contents:
{
"aud": "d43cfeb4-6b07-4b36-98ee-cc1a8f29b8a4",
"sub": "OrganizationalRoles",
"iss": "Suomi.fi-Valtuudet",
"sessionId": "\"a093bd1b-02a3-4b6d-b7a8-3eb1d399d468\"",
"iat": 1516778626,
"jti": "a386cf94-ecd1-4632-b456-bfabb9da3fb2",
"hetu": "010180-9026"
The clientId and the identifiers of the assignee and the assignor are relayed in the REST call. In addition, you can provide a mandate theme that determines the topic of the transaction along with the request. The mandate theme URI specified in the parameter may contain specifiers defined as query parameters. If specifiers are used in the URI, their keys and values should be represented in a URL-encoded format.
The Authorization response states whether the assignee has the right to act on behalf of the selected assignor. The right to act on behalf of the assignor is given in the authorization field and the favourable decision (ALLOWED) or negative decision (DISALLOWED) is returned as authorisation value. If the decision is DISALLOWED and the service is permitted to show the grounds for the rejection, they are returned in the reason fields of the list.
The identifier of the identified end user is relayed in the X-userId-HTTP header.
The table shows a response message to a successful Authorization REST query.
Element name | Type | Description | Domain |
|---|---|---|---|
result | string | Information on whether the assignee has the right to act on behalf of the assignor in the matter in question. | ALLOWED or DISALLOWED |
reasons | array<DecisionReason> | Value is conditional. There may be more than one element, one for each rejection ground. Use is separately agreed on in the service contract. | n* reason[rule, value] |
The table describes the DecisionReason element, which contains the elements reasonRule, reasonValue and valueType.
Element name | Type | Description | Domain |
|---|---|---|---|
reasonRule | string | identifier of the rule in question | |
reasonValue | string | reason localisation key | |
valueType | string | DESCRIPTION, EXCEPTION |
The table shows the information needed to call the Authorization REST interface.
Parameter | Type | Value/description |
|---|---|---|
service | path parameter | identifier of the service to be used (Web API Client ID) |
delegateId | path parameter | personal identity code of the assignee |
principalId | path parameter | personal identity code of the assignor |
requestId | request parameter | unique identifier of the request |
issue | request parameter | subject filter (mandate theme URI); optional, may be several |
Authorization REST
GET URL: {rova_host}/service/rest/hpa/authorization/{service}/{delegateId}/{principalId}?requestId={requestId}&issue={issue_uri}
Example request:
GET /service/rest/hpa/authorization/42bbe569/010180-9026/310813A951F?requestId=testClientRequestId HTTP/1.1
X-AsiointivaltuudetAuthorization: 42bbe569 2018-06-04T13:29:34.404Z ULETcXn2xNTb4m7CNeSH++GEgjbKqdaCKF2QFA265DU=
X-userId: rova-demo-user
Host: localhost:8102
Connection: Keep-Alive
Accept: application/json;charset=UTF-8
Accept-Encoding: gzip,deflate
Example response:
HTTP/1.1 200
Pragma: no-cache
Expires: 0
Cache-control: no-cache, no-store, max-age=0, must-revalidate
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
X-Frame-Options: DENY
Set-Cookie: JSESSIONID=F443FAB19C3D112017BC543A705F91C0; Path=/; HttpOnly
Content-Security-Policy: default-src 'self'; style-src 'self' 'unsafe-inline';
X-Application-Context: roles-auths-web-api:dev:8102
Content-Type: application/json;charset=UTF-8
Transfer-Encoding: chunked
Date: Mon, 04 Jun 2018 13:29:38 GMT
21
{"reasons":[],"result":"ALLOWED"}
0
Error messages
If there is an error in the request, the HTTP status corresponding to the error, any error message and the ReqId identifier (internal Suomi.fi e-Authorizations request identifier) corresponding to the error are returned as responses. The following is a sample response in the event of an error.
HTTP/1.1 500 Internal Server Error
Server: Apache-Coyote/1.1
Pragma: no-cache
Expires: 0
Cache-control: no-cache, no-store, max-age=0, must-revalidate
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
Content-Security-Policy: default-src 'self'; script-src 'self' 'unsafe-inline'; style-src 'self' 'unsafe-inline';
X-Application-Context: application:8102
Content-Type: application/json;charset=UTF-8
Transfer-Encoding: chunked
Date: Wed, 15 Jun 2016 10:32:20 GMT
Connection: close
{"errorMessage":"HTTP 500 Internal Server Error","errorCode": "OTHER_EXCEPTION","ReqID":"0STUQMODABLJ5ZW"}
Specifiers limit the authority of authorisations, for example, to a sub-organisation or unit. By default, mandate themes do not have specifiers, but one can be defined for them if necessary.
The types and names of specifiers are defined in the mandate code set. If limiting specifiers have been defined for a mandate code, they are added in the response after the mandate code identifier as key value pairs:
Authorization
GET URL: {rova_host}/service/hpa/api/authorization/{sessionId}/{personId}?requestId={requestId}&issues={issues}&access_token={access_token}
The URI for which authorisation is requested is used as the value of the Issues parameter. This parameter is not mandatory. There can be several parameters. The URI specified in the parameter may contain specifiers defined as query parameters. If specifiers are used in the URI, their keys and values should be represented in a URL-encoded format.
Example request:
GET /service/hpa/api/authorization/7407df88-8fbe-4e16-94fd-05467963b49e/120508A950F?requestId=testClientRequestId&issues=http%3A%2F%2Fvaltuusrekisteri.suomi.fi%2Fpalkkatietojen_ilmoittaminen%3FprincipalId%3D120508A950F%26subOrganization%3D1234567-1 HTTP/1.1
X-AsiointivaltuudetAuthorization: 42bbe569 2016-06-13T11:48:02.087Z vFxeTk/6oJlqHxhkE3YTyuTQh7X2SMrB/XhvAvemIuQ=
Host: localhost:18102
Accept: application/json;charset=UTF-8
Connection: keep-alive
Example response:
HTTP/1.1 200 OK
Server: Apache-Coyote/1.1
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
X-Application-Context: application:8102
Content-Type: application/json;charset=UTF-8
Transfer-Encoding: chunked
Date: Mon, 13 Jun 2016 11:48:02 GMT
[{"reasons":[],"result":"ALLOWED","principal":{"personId":"010316A998C","name":"Pekkala Esko-Olli"}}]
AuthorizationList
GET URL: {rova_host}/service/hpa/api/authorizationlist/{sessionId}/{personId}?requestId={requestId}&access_token={access_token}
Example request:
GET /service/hpa/api/authorizationlist/1bed4372-5706-4a3d-be1c-84a4c436636a/310813A951F?requestId=testClientRequestId&access_token=82e69cb5-b659-4dec-a12e-9fd9cf62db9f HTTP/1.1
X-AsiointivaltuudetAuthorization: 42bbe569 2017-10-25T05:22:03.873Z 1CngFqz1RPPSih0+4K8lsDa/e3rl79wywUP2hxkEJ6k=
Host: localhost:8102
Accept: application/json;charset=UTF-8
Connection: keep-alive
Example response:
HTTP/1.1 200
Set-Cookie: JSESSIONID=98A7D5AE47A0B927496AFC382FD5F65D;path=/;HttpOnly
X-Application-Context: roles-auths-web-api:8102
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
Content-Type: application/json;charset=UTF-8
Transfer-Encoding: chunked
Date: Wed, 25 Oct 2017 05:22:05 GMT
[{"reasons":[],"roles":["ALL"],"principal":{"personId":"010316A998C","name":"Pekkala Esko-Olli"}}]
Suomi.fi e-Authorizations uses OAuth 2.0 protocol to ensure a secure authorisation process. The correct use of OAuth sets requirements for e-services that use Suomi.fi e-Authorizations.
For general information about OAuth 2.0 protocol security, see OAuth specification documentOpens in a new window..
The e-service must be secured against CSRF attacks
When the end user is logged in to an e-service, they are vulnerable to CSRF attacks. In a CSRF attack, the functions of a e-service are linked from another service without the end user noticing. The e-service must be equipped with CSRF protection so that its functions cannot be called from outside the e-service.
Learn more about CSRF attacks.Opens in a new window.
The e-service must create and verify the OAuth state parameter
When the e-service starts OAuth authorisation, it must produce a unique identifier and attach it to the request as OAuth state parameter. Recommended options include a random identifier saved in the user session or a summary of the user session identifier and the e-service’s own secret.
Suomi.fi e-Authorizations returns the state parameter with the OAuth response, which the e-service must use to verify that the response to be processed originates from identification initiated by the e-service. This requirement is met when the roles-auth-client library is used.
The authorization’s return address must be entered as permitted redirection address
When the e-service starts the OAuth authorisation process, it relays to the e-Authorizations service a redirection address to which the user’s browser is directed at the end of the authorisation. In order to ensure that the OAuth key relayed with the return request does not end up in wrong hands, the e-Authorizations service will only assign the redirection to addresses provided to it in advance. The e-service must provide detailed redirection addresses to the e-Authorizations service as part of the connection process.
Learn more about redirecting OAuth 2.0Opens in a new window..
The e-service must end the Suomi.fi e-Authorizations session after verifying authorisation
After the e-service using Web API has made the required authorisation queries, it must close the session using the unregister function. Otherwise, the closing of the session is by timeout.
The e-service may not disclose the error messages returned by Suomi.fi e-Authorizations to the end user
To help resolve problems, Suomi.fi e-Authorizations may return information about the operation of internal components or identifiers as part of the error message. They are only intended for use between the e-service and Suomi.fi e-Authorizations. The e-service may not show the error messages to the end users in their original form.
Supported TLS protocols and encryption algorithms
Supported TLS protocols and encryption algorithms in the service address of the WEB API REST interface from 4 March 2025 onward:
TLS protocols
- TLS 1.2
- TLS 1.3
TLS 1.3 encryption algorithms
- TLS_AES_128_GCM_SHA256
- TLS_AES_256_GCM_SHA384
- TLS_CHACHA20_POLY1305_SHA256
TLS 1.2 encryption algorithms
- ECDHE-ECDSA-AES128-GCM-SHA256
- ECDHE-RSA-AES128-GCM-SHA256
- ECDHE-ECDSA-AES256-GCM-SHA384
- ECDHE-RSA-AES256-GCM-SHA384
Setting a server certificate as trusted
The server certificate may change at unannounced times. Therefore, we recommend that you set the AWS root certificates as trusted instead of the exact server certificate. Systems typically trust AWS root certificates by default. If necessary, root certificates can be downloaded from https://www.amazontrust.com/repository/.Opens in a new window.