Page tree
Skip to end of metadata
Go to start of metadata

Vēsture

VersionDescription
v.1Initial web version

apraksts

Signature creation and validation service API's (SignAPI) work is based on sessions.

Received session identifier shall be used in all future requests as reference to a specific set of files.

signAPI provides session storage on a perpetual basis and is used as an identifier for a particular file or set of files.

Service providers only need to retrieve the session identifier once and Service provider shall save session identifier with the parameters of a related particular file or set of files. 

Komponentes

SignAPI hosts

EnvironmentHost <SignAPI_base_url>
Testsignapi-prep.eparaksts.lv
Productionsignapi.eparaksts.lv

SignAPI interfaces

Session API

Description

Session API main scope is to manage file processing sessions.

Session API contains two methods

  • Create session
  • Close session


Session API URL
/api-session/v1.0/

Operations

MethodEndpointDescription
GET
start
Data processing session creation
GET
{sessionId}/close
Closing data processing session

Storage API

Description

Storage API main scope is to manage files or digests within the session.

Storage API contains following methods:

  • Upload file
  • Add document digest
  • List files
  • Download file
  • Delete file


Storage API URL
/api-storage/v1.0/

Operations

MethodEndpointDescription
PUT
{sessionId}/upload
Upload file
GET
{sessionId}/list
Retrieve file list in specific session
GET
{sessionId}/{documentiId}
Download file
DELETE
{sessionId}/{documentiId}
Delete file
POST
{sessionId}/addDocumentDigest
Add file digest and file name for signing.

Signing API

Description

Signing API main scope is to manage signatures/seals of archive timestamps within the session.

Signing API contains following methods:

  • Calculate digest
  • Finalize signing
  • Add archive timestamp
  • Create electronic seal


Signing API URI
/api-sign/v1.0/

Operations

MethodEndpointDescription
POST
calculateDigest
Signable data calculation.
POST
finalizeSigning
Signed document finalization.
POST
addArchive
Archive timestamp requesting.
POST
eSealCreate
Creates electronic seal with client provided electronic seal key.

Validation API

Description

Validation API main scope is to validate electronic signatures/seals of archive timestamps.

Validation API URI
/api-validation/v1.0/

Operations

MethodEndpointDescription
GET
{sessionId}/{documentiId}/validate
Validation of signed file

Share API

Description

Share API main scope is to manage session sharing.

Share API contains following methods:

  • Start sharing
  • Persons in session
  • Sessions of a Person
  • Remove sharing


Share API URI
/api-share/v1.0/

Operations

MethodEndpointDescription
POST
{sessionId}/persons
Add access rights to a specific session.
GET
{sessionId}/persons
Find out the persons with whom session is shared.
GET
{personId}/sessions
Find out the sessions which are shared with the specific person.
DELETE
{sessionId}/persons/{personId}
Remove access rights from the specific session.

Configuration API

Description

Configuration API main scope is to provide registered information to Service provider.

Configuration API URI
/api-config/v1.0/

Operations

MethodEndpointDescription
GET
Retrieve Service provider's configuration




Sesijas API

Izveidot sesiju

Scope

Ensure that a file processing session is created, which is then used to refer to the processes it takes.

Description

SignAPI creates a session folder that uses the session ID as folder name

Request

The Service provider's application sends the following GET request using TLS:

GET /api-session/v1.0/start

Authorization

The request must contain an Authorization header with an OAuth Introspect access token obtained via Integration Platform a Service provider's credentials grant flow.

Introspect piekļuves talona (token) saņemšana

Description

This operation obtains an OAuth 2.0 access token. This operation can be invoked as part of an OAuth 2.0 Service provider's credentials grant flow.

Introspect access token

When the Service provider's credentials grant flow is used, the obtained access token demonstrates the administrative authorization of the Service provider's application making the call for accessing certain resources or services (i.e., without direct intervention of the resource's owner), or for accessing resources of the Service provider's application. Token is issued when the authorization server that processes the request is not associated to an identity provider. A token of this type can be used for accessing resources not associated to end-users or to end-user resources of any domain.

This type of access token is used to get access to Signature creation and validation service API's

Request

To obtain the token, the Service provider's application must send a request like the following to authorization server using TLS. This request is sent directly from the Service provider’s application to authorization server and does not go via the browser.

POST /trustedx-authserver/oauth/{as}/token

Parameter

Title

Type

Field

Description

as

path

mandatory

Use "lvrtc-eipsign-as"

Host:

Test environment: eidas-demo.eparaksts.lv

Production: eidas.eparaksts.lv

Content-Type Header

Content-Type: application/x-www-form-urlencoded; charset=UTF-8


In HTTP POST request is necessary to incorporated the following main attribute: Authorization – API access token.

Authorization: Basic <API-Key>

How to generate API Access Key

Before Service provider access Integration platform API, LVRTC shall register Service provider as customer of Integration platform. After signing a contract with LVRTC (Test of Production environment) LVRTC generates Service Provider’s application identifier – (client_id) and shared secret (client_secret), intended for the customer usage.
API Access Key (API Key) is generated from the Service provider’s application identifier (client_id), a secret shared with the platform (client_secret)  on the following basis:

Service provider's application identifier client_id are converted using the UTF-8 character encoding and URL encoding conditions.

(warning)  For example, value "Portāls" conversion result is "port%C4%81ls".

Service provider's application password client_secret is converted by using the UTF-8 character encoding and URL encoding conditions.

(warning)  For example, value "drošība" conversion result is "dro%C5%A1%C4%ABba".

Both values of the previous two steps must be combined with separator colon “:” between them.

(warning)  For example, by using previous examples, the result will be "port%C4%81ls:dro%C5%A1%C4%ABba".

Obtained value must be converted using base 64 encoding without line breaks.

(warning)  For example, values "port%C4%81ls:dro%C5%A1%C4%ABba" conversion result is "CG94ydCVDNCUMWxzOmRybyVDNSVBMSVDNCVBQmJh".

"MIME Tools" tool in "Notepad + +" can be used for this purpose.

API-Key = base64[url_encode(utf8(<client_id>)) ':' url_encode(utf8(<client_secret>))]

Body

The content of the request for Introspect access token (used for access SignAPI service):

Property

Usage

Description

grant_type

mandatory

Must have the client_credentials value .

scopemandatoryMust have the urn:safelayer:eidas:oauth:token:introspect value

Example (Introspect access token)

The following example shows a situation in which the Service provider’s application with the identifier "Portal" and the password "drošība" authority shall transmit the request to the server with the identifier "lvrtc-eips-as":

POST /trustedx-authserver/oauth/lvrtc-eipsign-as/token HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Authorization: Basic CG94ydCVDNCUMWxzOmRybyVDNSVBMSVDNCVBQmJh
Host: eidas-demo.eparaksts.lv
grant_type=client_credentials&
			scope=urn%3Asafelayer%3Aeidas%3Aoauth%3Atoken%3Aintrospect

Response

In response, Integration platform authorization server issues a bearer-type OAuth 2.0 access token and returns it in a JSON structure.

{
"access_token" : {string}, 
"token_type" : "Bearer", 
"expires_in" : {number}
}

Parameter

PropertyDescription
access_token
Access token generated by Authorization server. The token has the characteristics specified in the configuration of the authorization server that processed the request and consists of a random string of the number of bytes specified in the Access token number of random bytes (by default, 32), encoded in hexadecimal.
token_type
Type of access token. Always has the "bearer" value. (Bearer type OAuth 2.0 access token).
expires_in
Lifetime (in seconds) of the access token. The Service provider’s application must perform the access the token authorizes before the token expires. This value can be configured in the Token timeout option of the authorization server (by default, 120 seconds). Once this timeout has expired, the token becomes invalid, and the Service provider’s application must obtain another one if it wants to continue invoking the protected services.

Example

Introspect access token:

HTTP/1.1 200 OK
Content-Type: application/json;charset=utf-8 
Cache-Control: no-store, no-cache, must-revalidate 
Pragma: no-cache
{
 "scope": "urn:safelayer:eidas:oauth:token:introspect",
 "access_token": "dfffb0d7f90bed142464750cacad5e4b9e23f58ecb1d77e3bdf706ba208ad16a",
 "token_type": "Bearer",
 "expires_in": 600
}



Example

GET /api-session/v1.0/start HTTP/1.1
Authorization: Bearer a477b3a3366768c07e4c458f518711b4b351e8d2c2f0f78a1524e4d3efd00603
Host: signapi-prep.eparaksts.lv

Response

JSON object:

{
    "data": {
        "sessionId": {string}
    }
}
PropertyTypeDescription
sessionIdString (64)

File processing session identifier.

Example

{
    "data": {
        "sessionId": "5a1ef5321d1bd9a2966d673c84c7ded630a1923965e3efcfc1787260cbe8223d"
    }
}




Pabeigt sesiju

Scope

Delete file processing session and related documents from memory.

Description

  1.  Deleting files stored and created in the file processing session.
  2.  Deleting the file processing session directory.

Request

The Service provider's application sends the following GET request using TLS:

GET /api-session/v1.0/{sessionId}/close
PlopertyTypeUsageDescription
sessionId
String (64)MandatorySession identifier

Authorization

The request must contain an Authorization header with an OAuth Introspect access token obtained via Integration Platform a Service provider's credentials grant flow.

Introspect piekļuves talona (token) saņemšana

Description

This operation obtains an OAuth 2.0 access token. This operation can be invoked as part of an OAuth 2.0 Service provider's credentials grant flow.

Introspect access token

When the Service provider's credentials grant flow is used, the obtained access token demonstrates the administrative authorization of the Service provider's application making the call for accessing certain resources or services (i.e., without direct intervention of the resource's owner), or for accessing resources of the Service provider's application. Token is issued when the authorization server that processes the request is not associated to an identity provider. A token of this type can be used for accessing resources not associated to end-users or to end-user resources of any domain.

This type of access token is used to get access to Signature creation and validation service API's

Request

To obtain the token, the Service provider's application must send a request like the following to authorization server using TLS. This request is sent directly from the Service provider’s application to authorization server and does not go via the browser.

POST /trustedx-authserver/oauth/{as}/token

Parameter

Title

Type

Field

Description

as

path

mandatory

Use "lvrtc-eipsign-as"

Host:

Test environment: eidas-demo.eparaksts.lv

Production: eidas.eparaksts.lv

Content-Type Header

Content-Type: application/x-www-form-urlencoded; charset=UTF-8


In HTTP POST request is necessary to incorporated the following main attribute: Authorization – API access token.

Authorization: Basic <API-Key>

How to generate API Access Key

Before Service provider access Integration platform API, LVRTC shall register Service provider as customer of Integration platform. After signing a contract with LVRTC (Test of Production environment) LVRTC generates Service Provider’s application identifier – (client_id) and shared secret (client_secret), intended for the customer usage.
API Access Key (API Key) is generated from the Service provider’s application identifier (client_id), a secret shared with the platform (client_secret)  on the following basis:

Service provider's application identifier client_id are converted using the UTF-8 character encoding and URL encoding conditions.

(warning)  For example, value "Portāls" conversion result is "port%C4%81ls".

Service provider's application password client_secret is converted by using the UTF-8 character encoding and URL encoding conditions.

(warning)  For example, value "drošība" conversion result is "dro%C5%A1%C4%ABba".

Both values of the previous two steps must be combined with separator colon “:” between them.

(warning)  For example, by using previous examples, the result will be "port%C4%81ls:dro%C5%A1%C4%ABba".

Obtained value must be converted using base 64 encoding without line breaks.

(warning)  For example, values "port%C4%81ls:dro%C5%A1%C4%ABba" conversion result is "CG94ydCVDNCUMWxzOmRybyVDNSVBMSVDNCVBQmJh".

"MIME Tools" tool in "Notepad + +" can be used for this purpose.

API-Key = base64[url_encode(utf8(<client_id>)) ':' url_encode(utf8(<client_secret>))]

Body

The content of the request for Introspect access token (used for access SignAPI service):

Property

Usage

Description

grant_type

mandatory

Must have the client_credentials value .

scopemandatoryMust have the urn:safelayer:eidas:oauth:token:introspect value

Example (Introspect access token)

The following example shows a situation in which the Service provider’s application with the identifier "Portal" and the password "drošība" authority shall transmit the request to the server with the identifier "lvrtc-eips-as":

POST /trustedx-authserver/oauth/lvrtc-eipsign-as/token HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Authorization: Basic CG94ydCVDNCUMWxzOmRybyVDNSVBMSVDNCVBQmJh
Host: eidas-demo.eparaksts.lv
grant_type=client_credentials&
			scope=urn%3Asafelayer%3Aeidas%3Aoauth%3Atoken%3Aintrospect

Response

In response, Integration platform authorization server issues a bearer-type OAuth 2.0 access token and returns it in a JSON structure.

{
"access_token" : {string}, 
"token_type" : "Bearer", 
"expires_in" : {number}
}

Parameter

PropertyDescription
access_token
Access token generated by Authorization server. The token has the characteristics specified in the configuration of the authorization server that processed the request and consists of a random string of the number of bytes specified in the Access token number of random bytes (by default, 32), encoded in hexadecimal.
token_type
Type of access token. Always has the "bearer" value. (Bearer type OAuth 2.0 access token).
expires_in
Lifetime (in seconds) of the access token. The Service provider’s application must perform the access the token authorizes before the token expires. This value can be configured in the Token timeout option of the authorization server (by default, 120 seconds). Once this timeout has expired, the token becomes invalid, and the Service provider’s application must obtain another one if it wants to continue invoking the protected services.

Example

Introspect access token:

HTTP/1.1 200 OK
Content-Type: application/json;charset=utf-8 
Cache-Control: no-store, no-cache, must-revalidate 
Pragma: no-cache
{
 "scope": "urn:safelayer:eidas:oauth:token:introspect",
 "access_token": "dfffb0d7f90bed142464750cacad5e4b9e23f58ecb1d77e3bdf706ba208ad16a",
 "token_type": "Bearer",
 "expires_in": 600
}



Example

GET /api-session/v1.0/77740b301f0880ef498cb1e474e8060b3e538cfeea8ebf508c2bad4b72b56a87/close HTTP/1.1
Authorization: Bearer a477b3a3366768c07e4c458f518711b4b351e8d2c2f0f78a1524e4d3efd00603
Host: signapi-prep.eparaksts.lv

Response

JSON object:

{
    "data": "Session {sessionId} closed"
}
PropertyTypeDescription
sessionId
StringFile processing session identifier


Example

{
    "data": "Session 77740b301f0880ef498cb1e474e8060b3e538cfeea8ebf508c2bad4b72b56a87 closed"
}




Uzglabāšanas API

Datņu augšupielāde

Scope

New file adding to the specific file processing session.

Description

1. The file is attached to the file processing session;
2. The file description information is returned.

Request

The Service provider's application sends the following GET request using TLS:

PUT /api-storage/v1.0/{sessionId}/upload 
PropertyTypeUsageDescription
sessionId
String (64)MandatoryFile processing session identifier

Authorization

The request must contain an Authorization header with an OAuth Introspect access token obtained via Integration Platform a Service provider's credentials grant flow.

Introspect piekļuves talona (token) saņemšana

Description

This operation obtains an OAuth 2.0 access token. This operation can be invoked as part of an OAuth 2.0 Service provider's credentials grant flow.

Introspect access token

When the Service provider's credentials grant flow is used, the obtained access token demonstrates the administrative authorization of the Service provider's application making the call for accessing certain resources or services (i.e., without direct intervention of the resource's owner), or for accessing resources of the Service provider's application. Token is issued when the authorization server that processes the request is not associated to an identity provider. A token of this type can be used for accessing resources not associated to end-users or to end-user resources of any domain.

This type of access token is used to get access to Signature creation and validation service API's

Request

To obtain the token, the Service provider's application must send a request like the following to authorization server using TLS. This request is sent directly from the Service provider’s application to authorization server and does not go via the browser.

POST /trustedx-authserver/oauth/{as}/token

Parameter

Title

Type

Field

Description

as

path

mandatory

Use "lvrtc-eipsign-as"

Host:

Test environment: eidas-demo.eparaksts.lv

Production: eidas.eparaksts.lv

Content-Type Header

Content-Type: application/x-www-form-urlencoded; charset=UTF-8


In HTTP POST request is necessary to incorporated the following main attribute: Authorization – API access token.

Authorization: Basic <API-Key>

How to generate API Access Key

Before Service provider access Integration platform API, LVRTC shall register Service provider as customer of Integration platform. After signing a contract with LVRTC (Test of Production environment) LVRTC generates Service Provider’s application identifier – (client_id) and shared secret (client_secret), intended for the customer usage.
API Access Key (API Key) is generated from the Service provider’s application identifier (client_id), a secret shared with the platform (client_secret)  on the following basis:

Service provider's application identifier client_id are converted using the UTF-8 character encoding and URL encoding conditions.

(warning)  For example, value "Portāls" conversion result is "port%C4%81ls".

Service provider's application password client_secret is converted by using the UTF-8 character encoding and URL encoding conditions.

(warning)  For example, value "drošība" conversion result is "dro%C5%A1%C4%ABba".

Both values of the previous two steps must be combined with separator colon “:” between them.

(warning)  For example, by using previous examples, the result will be "port%C4%81ls:dro%C5%A1%C4%ABba".

Obtained value must be converted using base 64 encoding without line breaks.

(warning)  For example, values "port%C4%81ls:dro%C5%A1%C4%ABba" conversion result is "CG94ydCVDNCUMWxzOmRybyVDNSVBMSVDNCVBQmJh".

"MIME Tools" tool in "Notepad + +" can be used for this purpose.

API-Key = base64[url_encode(utf8(<client_id>)) ':' url_encode(utf8(<client_secret>))]

Body

The content of the request for Introspect access token (used for access SignAPI service):

Property

Usage

Description

grant_type

mandatory

Must have the client_credentials value .

scopemandatoryMust have the urn:safelayer:eidas:oauth:token:introspect value

Example (Introspect access token)

The following example shows a situation in which the Service provider’s application with the identifier "Portal" and the password "drošība" authority shall transmit the request to the server with the identifier "lvrtc-eips-as":

POST /trustedx-authserver/oauth/lvrtc-eipsign-as/token HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Authorization: Basic CG94ydCVDNCUMWxzOmRybyVDNSVBMSVDNCVBQmJh
Host: eidas-demo.eparaksts.lv
grant_type=client_credentials&
			scope=urn%3Asafelayer%3Aeidas%3Aoauth%3Atoken%3Aintrospect

Response

In response, Integration platform authorization server issues a bearer-type OAuth 2.0 access token and returns it in a JSON structure.

{
"access_token" : {string}, 
"token_type" : "Bearer", 
"expires_in" : {number}
}

Parameter

PropertyDescription
access_token
Access token generated by Authorization server. The token has the characteristics specified in the configuration of the authorization server that processed the request and consists of a random string of the number of bytes specified in the Access token number of random bytes (by default, 32), encoded in hexadecimal.
token_type
Type of access token. Always has the "bearer" value. (Bearer type OAuth 2.0 access token).
expires_in
Lifetime (in seconds) of the access token. The Service provider’s application must perform the access the token authorizes before the token expires. This value can be configured in the Token timeout option of the authorization server (by default, 120 seconds). Once this timeout has expired, the token becomes invalid, and the Service provider’s application must obtain another one if it wants to continue invoking the protected services.

Example

Introspect access token:

HTTP/1.1 200 OK
Content-Type: application/json;charset=utf-8 
Cache-Control: no-store, no-cache, must-revalidate 
Pragma: no-cache
{
 "scope": "urn:safelayer:eidas:oauth:token:introspect",
 "access_token": "dfffb0d7f90bed142464750cacad5e4b9e23f58ecb1d77e3bdf706ba208ad16a",
 "token_type": "Bearer",
 "expires_in": 600
}



Body

PropertyTypeUsageDescription
file
Binary dataMandatoryFile to be uploaded


Example

PUT /api-storage/v1.0/77740b301f0880ef498cb1e474e8060b3e538cfeea8ebf508c2bad4b72b56a87/upload HTTP/1.1
Authorization: Bearer a477b3a3366768c07e4c458f518711b4b351e8d2c2f0f78a1524e4d3efd00603
Host: signapi-prep.eparaksts.lv

Response

JSON object:

{
    "data": [ 
				{
        	"includedDocuments": [
            	{
              	  "id": {String},
             	   "name": {String},
             	   "size": {Number},
					"type": {String}
				}
        	],
        	"id": {String},
        	"name": {String},
       		"size": {Number},
			"type": {String}
		 		}
			]
}
PropertyTypeDescription
data
Object
Data Object
data.includedDocuments
Array
If uploaded file is ASICE (EDOC), list of files included in ASIC container.
data.includedDocuments.id
String
Included file identifier, must be used if you need to download current included file.
data.includedDocuments.name
String
Included file name.
data.includedDocuments.size
Number
Included file size in bytes
data.includedDocuments.type
String

Processed file type.

"file" - In case of file or ASICE container

data.id
String
File Identifier (documentId)
data.name
String
File name
data.size
Integer
File size in bytes
data.type
String

Processed file type:

"file" - In case of file or ASICE container

Example if uploaded file is not ASICE container

{
    "data": {
        "id": "cc8bcb560bbfee4c190433ea63c549d1",
        "name": "test.doc",
        "size": 41280,
		"type": "file"
 			}
}

Example if ASICE container is uploaded 

{
    "data": {
        "includedDocuments": [
            {
                "id": "3cbc266934776e581bcb406f15bb5ffd",
                "name": "Receipt.doc",
                "size": 22528,
				"type": "file"
 			}
        ],
        "id": "23a3abe0a211478ae55554649178568e",
        "name": "Receipt.edoc",
        "size": 14805,
		"type": "file"
 			}
}




Dokumenta kopsavilkuma pievienošana

Scope

Purpose of the "Add document digest" operation is to avoid file transfering (if there is extra security requirements) out of internal network.

Operation add signable file digest (HASH) and filename to the file processing session.

Only possible for signing ASICE (EDOC) document types.

Description

1. The file digest and file name is attached to the file processing session;
2. The file description information is returned.

Request

The Service provider's application sends the following GET request using TLS:

POST /api-storage/v1.0/{sessionId}/addDocumentDigest 
PropertyTypeUsageDescription
sessionId
String (64)MandatoryFile processing session identifier

Authorization

The request must contain an Authorization header with an OAuth Introspect access token obtained via Integration Platform a Service provider's credentials grant flow.

Introspect piekļuves talona (token) saņemšana

Description

This operation obtains an OAuth 2.0 access token. This operation can be invoked as part of an OAuth 2.0 Service provider's credentials grant flow.

Introspect access token

When the Service provider's credentials grant flow is used, the obtained access token demonstrates the administrative authorization of the Service provider's application making the call for accessing certain resources or services (i.e., without direct intervention of the resource's owner), or for accessing resources of the Service provider's application. Token is issued when the authorization server that processes the request is not associated to an identity provider. A token of this type can be used for accessing resources not associated to end-users or to end-user resources of any domain.

This type of access token is used to get access to Signature creation and validation service API's

Request

To obtain the token, the Service provider's application must send a request like the following to authorization server using TLS. This request is sent directly from the Service provider’s application to authorization server and does not go via the browser.

POST /trustedx-authserver/oauth/{as}/token

Parameter

Title

Type

Field

Description

as

path

mandatory

Use "lvrtc-eipsign-as"

Host:

Test environment: eidas-demo.eparaksts.lv

Production: eidas.eparaksts.lv

Content-Type Header

Content-Type: application/x-www-form-urlencoded; charset=UTF-8


In HTTP POST request is necessary to incorporated the following main attribute: Authorization – API access token.

Authorization: Basic <API-Key>

How to generate API Access Key

Before Service provider access Integration platform API, LVRTC shall register Service provider as customer of Integration platform. After signing a contract with LVRTC (Test of Production environment) LVRTC generates Service Provider’s application identifier – (client_id) and shared secret (client_secret), intended for the customer usage.
API Access Key (API Key) is generated from the Service provider’s application identifier (client_id), a secret shared with the platform (client_secret)  on the following basis:

Service provider's application identifier client_id are converted using the UTF-8 character encoding and URL encoding conditions.

(warning)  For example, value "Portāls" conversion result is "port%C4%81ls".

Service provider's application password client_secret is converted by using the UTF-8 character encoding and URL encoding conditions.

(warning)  For example, value "drošība" conversion result is "dro%C5%A1%C4%ABba".

Both values of the previous two steps must be combined with separator colon “:” between them.

(warning)  For example, by using previous examples, the result will be "port%C4%81ls:dro%C5%A1%C4%ABba".

Obtained value must be converted using base 64 encoding without line breaks.

(warning)  For example, values "port%C4%81ls:dro%C5%A1%C4%ABba" conversion result is "CG94ydCVDNCUMWxzOmRybyVDNSVBMSVDNCVBQmJh".

"MIME Tools" tool in "Notepad + +" can be used for this purpose.

API-Key = base64[url_encode(utf8(<client_id>)) ':' url_encode(utf8(<client_secret>))]

Body

The content of the request for Introspect access token (used for access SignAPI service):

Property

Usage

Description

grant_type

mandatory

Must have the client_credentials value .

scopemandatoryMust have the urn:safelayer:eidas:oauth:token:introspect value

Example (Introspect access token)

The following example shows a situation in which the Service provider’s application with the identifier "Portal" and the password "drošība" authority shall transmit the request to the server with the identifier "lvrtc-eips-as":

POST /trustedx-authserver/oauth/lvrtc-eipsign-as/token HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Authorization: Basic CG94ydCVDNCUMWxzOmRybyVDNSVBMSVDNCVBQmJh
Host: eidas-demo.eparaksts.lv
grant_type=client_credentials&
			scope=urn%3Asafelayer%3Aeidas%3Aoauth%3Atoken%3Aintrospect

Response

In response, Integration platform authorization server issues a bearer-type OAuth 2.0 access token and returns it in a JSON structure.

{
"access_token" : {string}, 
"token_type" : "Bearer", 
"expires_in" : {number}
}

Parameter

PropertyDescription
access_token
Access token generated by Authorization server. The token has the characteristics specified in the configuration of the authorization server that processed the request and consists of a random string of the number of bytes specified in the Access token number of random bytes (by default, 32), encoded in hexadecimal.
token_type
Type of access token. Always has the "bearer" value. (Bearer type OAuth 2.0 access token).
expires_in
Lifetime (in seconds) of the access token. The Service provider’s application must perform the access the token authorizes before the token expires. This value can be configured in the Token timeout option of the authorization server (by default, 120 seconds). Once this timeout has expired, the token becomes invalid, and the Service provider’s application must obtain another one if it wants to continue invoking the protected services.

Example

Introspect access token:

HTTP/1.1 200 OK
Content-Type: application/json;charset=utf-8 
Cache-Control: no-store, no-cache, must-revalidate 
Pragma: no-cache
{
 "scope": "urn:safelayer:eidas:oauth:token:introspect",
 "access_token": "dfffb0d7f90bed142464750cacad5e4b9e23f58ecb1d77e3bdf706ba208ad16a",
 "token_type": "Bearer",
 "expires_in": 600
}



Body

{
    "files": [
            {
                "name": {String},
                "digest": {String},
				"digest_algorithm": {String}
            }
        ],
    "signatureIndex": {String}
}

PropertyTypeUsageDescription
files
Array
MandatoryFile digest and name array
files.name
String
MandatoryThe name of the file (with extension) from which the diggest was calculated
files.digest
String
MandatoryCalculated file digest in Base64 encoding. (warning) See note below.
files.digest_algorithm
String
MandatoryUsed HASH Algorithm (Only SHA256 is supported)
signatureIndex
String
Optional

Signature sequence index, starting with "0", which means the first signature (XAdES signature file name signatures0.xml)

If Property is not used, signature index will be "0".

(warning) If there is planed that file will be signed by more than one signer, this parameter shall be used by increasing by 1 for each next signature. ASICE container can't contain more then one signature with same file name.

Otherwise, service provider shall rename signature file before adding it to ASICE container.

File diggest calculation

(warning) Only SHA256 at this moment is supported.

(lightbulb) Fist calculate SHA256 HASH from the file you need to sign. Then take SHA256 HASH and make HEX to Base64 encoding. For example encoding you can use https://base64.guru/converter/encode/hex

Guidelines for using file digest till ASICE finalizing.

Guidelines for using file digest till ASICE finalizing.

Digest preparation and signing

  1. Hash from files to be signed shall be calculated at service provider premises.
  2. Digest shall be encoded from calculated hash (HEX to Base64).
  3. Service provider shall receive authorisation token (Introspect scope) for accessing SignAPI
  4. Request "Add document digest" operation  (POST /api-storage/v1.0/{sessionId}/addDocumentDigest)
  5. Request "Calculate Digest" operation (POST /api-sign/v1.0/calculateDigest)
  6. Request "Finalize Signing" operation (POST /api-sign/v1.0/finalizeSigning)
  7. Request "File list" operation (GET /api-session/v1.0/{sessionId}/list) - get ASICE container "documentId" property
  8. Request "File download" operation (GET /api-session/v1.0/{sessionId}/{documentId}) - download signed ASICE container.
  9. Open container with zip processing tools (probably need to rename extension to ".zip").
  10. Add file, from which digest was calculated to container's root folder.
  11. When file is added - change extension back to ".edoc" or ".asice" if needed.

Adding additional signature to existing ASICE container

(in case when file digest is signed by more than one signer)

  1. If you have already signed ASICE with at least one signature, and you don't have stored signed file/s digest:
  2. Unpack ASICE container - extract file/s to be signed;
  3. Follow steps 1 to 9 from "Digest preparation and signing";
  4. Go to "META-INF" folder and extract signature XML file (Shall contain "signatures" name within file name (signatures1.xml));
  5. Open existing ASICE (where you want to add signature);
  6. Open "META-INF" folder:
  7. Check, if folder did not contain signature file with same filename as extracted in step 4:
    1. if contains, rename index of signature XML file extracted in step 4
  8. Add signature XML file to the "META-INF" folder
  9. When signature XML file is added - change extension back to ".edoc" or ".asice" if needed.





Superted HASH'es

Only SHA256 HASH is supported

ASICE and EDOC

EDOC container is Equal to ASIC container just uses ".edoc" extension.

".edoc" is popular extension (legacy) in Latvia, but ".asice" extensions are used as well and are supported.

".asice" extension is EU recognized (in countries where ASICE containers are in use).

ASICE container contains XAdES (XML Advanced electronic signature).






Signature XML files

ASICE container contains "META-INF" folder

Each signature creates a single XML file

Signature XML files Shall contain name "signatures" + index (in case of API "signatures0.xml or signatures1.xml")

All signature names shall be uniqe

(lightbulb) To avoid same names, use "signatureIndex" property in "Add Document Digest" operation

Example with one file digest and name

POST /api-storage/v1.0/77740b301f0880ef498cb1e474e8060b3e538cfeea8ebf508c2bad4b72b56a87/addDocumentDigest HTTP/1.1
Authorization: Bearer a477b3a3366768c07e4c458f518711b4b351e8d2c2f0f78a1524e4d3efd00603
Host: signapi-prep.eparaksts.lv
{
    "files": [
            {
                "name": "10-10.pdf",
                "digest": "u69UTpGwlSfNpIMYhXPIa612ELFu+Y8zWaVCApzlQdE=",
				"digest_algorithm": "SHA256"
            }
        ],
    "signatureIndex": "0"
}


Example with multiple file digest and name

POST /api-storage/v1.0/77740b301f0880ef498cb1e474e8060b3e538cfeea8ebf508c2bad4b72b56a87/addDocumentDigest HTTP/1.1
Authorization: Bearer a477b3a3366768c07e4c458f518711b4b351e8d2c2f0f78a1524e4d3efd00603
Host: signapi-prep.eparaksts.lv
{
    "files": [
            {
                "name": "10-10.pdf",
                "digest": "u69UTpGwlSfNpIMYhXPIa612ELFu+Y8zWaVCApzlQdE=",
				"digest_algorithm": "SHA256"
            },
            {
                "name": "10-11.docx",
                "digest": "u69UTpGwlSfNpIMYhXPIa612ELFu+Y8zWaVCApzlQdB=",
				"digest_algorithm": "SHA256"
            },
            {
                "name": "10-12.pdf",
                "digest": "u69UTpGwlSfNpIMYhXPIa612ELFu+Y8zWaVCApzlQdC=",
				"digest_algorithm": "SHA256"
            }
        ],
    "signatureIndex": "0"
}

Response

JSON object:

{
    "data": [
        {
            "id": {String},
            "name": {String},
            "size": {Number},
			"type": {String}
        }
    ]
}
PropertyTypeDescription
data
Object
Data Object
data.id
String
File Identifier (documentId)
data.name
String
File name
data.size
Integer
File size in bytes (always will be "0" since filename and digest was added)
data.type
String

Processed file type:

"hash" - In case if file digest and file name is added to session

Example if one file digest and name

{
    "data": [
        {
            "id": "6921c9e8afd22a9a391d5318e08da85d",
            "name": "10-10.pdf",
            "size": 0,
			"type": "hash"
        }
    ]
}

Example if multiple file digest and name is added

{
    "data": [
        {
            "id": "6921c9e8afd22a9a391d5318e08da85d",
            "name": "10-10.pdf",
            "size": 0,
			"type": "hash"
        },
        {
            "id": "9f1702526028570f5f6c2813417797a0",
            "name": "10-11.docx",
            "size": 0,
			"type": "hash"
        },
        {
            "id": "5d05429bc930622ee008ed4ded1b2de1",
            "name": "10-12.pdf",
            "size": 0,
			"type": "hash"
        }
    ]
}

Datņu saraksts

Scope

Retrieve a list of files in a file processing session.

Description

1. Returns information about files stored in the file processing session:
1.1. If the session files are not yet signed, a list of all files is returned;
1.2. If the session files are signed, the signed file (EDOC / PDF) is returned.

Request

The Service provider's application sends the following GET request using TLS:

GET /api-storage/v1.0/{sessionId}/list
PropertyTypeUsageDescription
sessionId
String (64)MandatoryFile processing session identifier

Authorization

The request must contain an Authorization header with an OAuth Introspect access token obtained via Integration Platform a Service provider's credentials grant flow.

Introspect piekļuves talona (token) saņemšana

Description

This operation obtains an OAuth 2.0 access token. This operation can be invoked as part of an OAuth 2.0 Service provider's credentials grant flow.

Introspect access token

When the Service provider's credentials grant flow is used, the obtained access token demonstrates the administrative authorization of the Service provider's application making the call for accessing certain resources or services (i.e., without direct intervention of the resource's owner), or for accessing resources of the Service provider's application. Token is issued when the authorization server that processes the request is not associated to an identity provider. A token of this type can be used for accessing resources not associated to end-users or to end-user resources of any domain.

This type of access token is used to get access to Signature creation and validation service API's

Request

To obtain the token, the Service provider's application must send a request like the following to authorization server using TLS. This request is sent directly from the Service provider’s application to authorization server and does not go via the browser.

POST /trustedx-authserver/oauth/{as}/token

Parameter

Title

Type

Field

Description

as

path

mandatory

Use "lvrtc-eipsign-as"

Host:

Test environment: eidas-demo.eparaksts.lv

Production: eidas.eparaksts.lv

Content-Type Header

Content-Type: application/x-www-form-urlencoded; charset=UTF-8


In HTTP POST request is necessary to incorporated the following main attribute: Authorization – API access token.

Authorization: Basic <API-Key>

How to generate API Access Key

Before Service provider access Integration platform API, LVRTC shall register Service provider as customer of Integration platform. After signing a contract with LVRTC (Test of Production environment) LVRTC generates Service Provider’s application identifier – (client_id) and shared secret (client_secret), intended for the customer usage.
API Access Key (API Key) is generated from the Service provider’s application identifier (client_id), a secret shared with the platform (client_secret)  on the following basis:

Service provider's application identifier client_id are converted using the UTF-8 character encoding and URL encoding conditions.

(warning)  For example, value "Portāls" conversion result is "port%C4%81ls".

Service provider's application password client_secret is converted by using the UTF-8 character encoding and URL encoding conditions.

(warning)  For example, value "drošība" conversion result is "dro%C5%A1%C4%ABba".

Both values of the previous two steps must be combined with separator colon “:” between them.

(warning)  For example, by using previous examples, the result will be "port%C4%81ls:dro%C5%A1%C4%ABba".

Obtained value must be converted using base 64 encoding without line breaks.

(warning)  For example, values "port%C4%81ls:dro%C5%A1%C4%ABba" conversion result is "CG94ydCVDNCUMWxzOmRybyVDNSVBMSVDNCVBQmJh".

"MIME Tools" tool in "Notepad + +" can be used for this purpose.

API-Key = base64[url_encode(utf8(<client_id>)) ':' url_encode(utf8(<client_secret>))]

Body

The content of the request for Introspect access token (used for access SignAPI service):

Property

Usage

Description

grant_type

mandatory

Must have the client_credentials value .

scopemandatoryMust have the urn:safelayer:eidas:oauth:token:introspect value

Example (Introspect access token)

The following example shows a situation in which the Service provider’s application with the identifier "Portal" and the password "drošība" authority shall transmit the request to the server with the identifier "lvrtc-eips-as":

POST /trustedx-authserver/oauth/lvrtc-eipsign-as/token HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Authorization: Basic CG94ydCVDNCUMWxzOmRybyVDNSVBMSVDNCVBQmJh
Host: eidas-demo.eparaksts.lv
grant_type=client_credentials&
			scope=urn%3Asafelayer%3Aeidas%3Aoauth%3Atoken%3Aintrospect

Response

In response, Integration platform authorization server issues a bearer-type OAuth 2.0 access token and returns it in a JSON structure.

{
"access_token" : {string}, 
"token_type" : "Bearer", 
"expires_in" : {number}
}

Parameter

PropertyDescription
access_token
Access token generated by Authorization server. The token has the characteristics specified in the configuration of the authorization server that processed the request and consists of a random string of the number of bytes specified in the Access token number of random bytes (by default, 32), encoded in hexadecimal.
token_type
Type of access token. Always has the "bearer" value. (Bearer type OAuth 2.0 access token).
expires_in
Lifetime (in seconds) of the access token. The Service provider’s application must perform the access the token authorizes before the token expires. This value can be configured in the Token timeout option of the authorization server (by default, 120 seconds). Once this timeout has expired, the token becomes invalid, and the Service provider’s application must obtain another one if it wants to continue invoking the protected services.

Example

Introspect access token:

HTTP/1.1 200 OK
Content-Type: application/json;charset=utf-8 
Cache-Control: no-store, no-cache, must-revalidate 
Pragma: no-cache
{
 "scope": "urn:safelayer:eidas:oauth:token:introspect",
 "access_token": "dfffb0d7f90bed142464750cacad5e4b9e23f58ecb1d77e3bdf706ba208ad16a",
 "token_type": "Bearer",
 "expires_in": 600
}



Example

GET /api-storage/v1.0/77740b301f0880ef498cb1e474e8060b3e538cfeea8ebf508c2bad4b72b56a87/list HTTP/1.1
Authorization: Bearer a477b3a3366768c07e4c458f518711b4b351e8d2c2f0f78a1524e4d3efd00603
Host: signapi-prep.eparaksts.lv

Response

JSON object:

{
    "data": {
        "includedDocuments": [
            {
                "id": {String},
                "name": {String},
                "size": {Number},
				"type": {String}
 			}
        ],
        "id": {String},
        "name": {String},
        "size": {Number},
		"type": {String}
 			}
}

PropertyTypeDescription
data
Object
Data Object
data.includedDocuments
Array

Files included in signed container

data.includedDocuments.id
String
Included file Identifier (documentId)
data.includedDocuments.name
String
Included file name
data.includedDocuments.size
Integer
Included file size in bytes
data.includedDocuments.type
String

Processed file type:

"file" - In case of file or ASICE container

"hash" - In case if file digest and file name is added to session
data.id
String
File Identifier (documentId)
data.name
String
File name  File size in bytes
data.size
String 
File size in bytes
data.type
String 

Processed file type:

"file" - In case of file or ASICE container

"hash" - In case if file digest and file name is added to session


Examples

Example of ASICE container containing one file
{
    "data": {
        "includedDocuments": [
            {
                "id": "3cbc266934776e581bcb406f15bb5ffd",
                "name": "Receipt.doc",
                "size": 22528,
				"type": "file"
			}
        ],
        "id": "23a3abe0a211478ae55554649178568e",
        "name": "Receipt.edoc",
        "size": 14805,
		"type": "file"
 			}
}
Example of ASICE container when file digest and name is signed
 {
    "data": [
        {
            "includedDocuments": [
                {
                    "id": "dc7a737f0d3dcb288902ed1df4942ee3",
                    "name": "Report.docx",
                    "size": 0,
                    "type": "hash"
                }
            ],
            "id": "592ad9f0c4f9356db0d0d3716a87d5f1",
            "name": "DigestEdoc.edoc",
            "size": 8891,
            "type": "file"
        }
    ]
}




Datņu lejupielāde

Scope

Download a file from the file processing session

Description

Returns a requested file.

Request

The Service provider's application sends the following GET request using TLS:

GET /api-storage/v1.0/{sessionId}/{documentId}
PropertyTypeUsageDescription
sessionId
String (64)MandatoryFile processing session identifier
documentId
String (64)MandatoryDocument identifier, received from "upload" or "list" operation as "id" property

Authorization

The request must contain an Authorization header with an OAuth Introspect access token obtained via Integration Platform a Service provider's credentials grant flow.

Introspect piekļuves talona (token) saņemšana

Description

This operation obtains an OAuth 2.0 access token. This operation can be invoked as part of an OAuth 2.0 Service provider's credentials grant flow.

Introspect access token

When the Service provider's credentials grant flow is used, the obtained access token demonstrates the administrative authorization of the Service provider's application making the call for accessing certain resources or services (i.e., without direct intervention of the resource's owner), or for accessing resources of the Service provider's application. Token is issued when the authorization server that processes the request is not associated to an identity provider. A token of this type can be used for accessing resources not associated to end-users or to end-user resources of any domain.

This type of access token is used to get access to Signature creation and validation service API's

Request

To obtain the token, the Service provider's application must send a request like the following to authorization server using TLS. This request is sent directly from the Service provider’s application to authorization server and does not go via the browser.

POST /trustedx-authserver/oauth/{as}/token

Parameter

Title

Type

Field

Description

as

path

mandatory

Use "lvrtc-eipsign-as"

Host:

Test environment: eidas-demo.eparaksts.lv

Production: eidas.eparaksts.lv

Content-Type Header

Content-Type: application/x-www-form-urlencoded; charset=UTF-8


In HTTP POST request is necessary to incorporated the following main attribute: Authorization – API access token.

Authorization: Basic <API-Key>

How to generate API Access Key

Before Service provider access Integration platform API, LVRTC shall register Service provider as customer of Integration platform. After signing a contract with LVRTC (Test of Production environment) LVRTC generates Service Provider’s application identifier – (client_id) and shared secret (client_secret), intended for the customer usage.
API Access Key (API Key) is generated from the Service provider’s application identifier (client_id), a secret shared with the platform (client_secret)  on the following basis:

Service provider's application identifier client_id are converted using the UTF-8 character encoding and URL encoding conditions.

(warning)  For example, value "Portāls" conversion result is "port%C4%81ls".

Service provider's application password client_secret is converted by using the UTF-8 character encoding and URL encoding conditions.

(warning)  For example, value "drošība" conversion result is "dro%C5%A1%C4%ABba".

Both values of the previous two steps must be combined with separator colon “:” between them.

(warning)  For example, by using previous examples, the result will be "port%C4%81ls:dro%C5%A1%C4%ABba".

Obtained value must be converted using base 64 encoding without line breaks.

(warning)  For example, values "port%C4%81ls:dro%C5%A1%C4%ABba" conversion result is "CG94ydCVDNCUMWxzOmRybyVDNSVBMSVDNCVBQmJh".

"MIME Tools" tool in "Notepad + +" can be used for this purpose.

API-Key = base64[url_encode(utf8(<client_id>)) ':' url_encode(utf8(<client_secret>))]

Body

The content of the request for Introspect access token (used for access SignAPI service):

Property

Usage

Description

grant_type

mandatory

Must have the client_credentials value .

scopemandatoryMust have the urn:safelayer:eidas:oauth:token:introspect value

Example (Introspect access token)

The following example shows a situation in which the Service provider’s application with the identifier "Portal" and the password "drošība" authority shall transmit the request to the server with the identifier "lvrtc-eips-as":

POST /trustedx-authserver/oauth/lvrtc-eipsign-as/token HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Authorization: Basic CG94ydCVDNCUMWxzOmRybyVDNSVBMSVDNCVBQmJh
Host: eidas-demo.eparaksts.lv
grant_type=client_credentials&
			scope=urn%3Asafelayer%3Aeidas%3Aoauth%3Atoken%3Aintrospect

Response

In response, Integration platform authorization server issues a bearer-type OAuth 2.0 access token and returns it in a JSON structure.

{
"access_token" : {string}, 
"token_type" : "Bearer", 
"expires_in" : {number}
}

Parameter

PropertyDescription
access_token
Access token generated by Authorization server. The token has the characteristics specified in the configuration of the authorization server that processed the request and consists of a random string of the number of bytes specified in the Access token number of random bytes (by default, 32), encoded in hexadecimal.
token_type
Type of access token. Always has the "bearer" value. (Bearer type OAuth 2.0 access token).
expires_in
Lifetime (in seconds) of the access token. The Service provider’s application must perform the access the token authorizes before the token expires. This value can be configured in the Token timeout option of the authorization server (by default, 120 seconds). Once this timeout has expired, the token becomes invalid, and the Service provider’s application must obtain another one if it wants to continue invoking the protected services.

Example

Introspect access token:

HTTP/1.1 200 OK
Content-Type: application/json;charset=utf-8 
Cache-Control: no-store, no-cache, must-revalidate 
Pragma: no-cache
{
 "scope": "urn:safelayer:eidas:oauth:token:introspect",
 "access_token": "dfffb0d7f90bed142464750cacad5e4b9e23f58ecb1d77e3bdf706ba208ad16a",
 "token_type": "Bearer",
 "expires_in": 600
}



Example

GET /api-storage/v1.0/cd6afb8b7e9fd6aa2b2ef7b981fa98cb59128fdef6c064f74dc9cef529a79d17/cc8bcb560bbfee4c190433ea63c549d1
HTTP/1.1
Authorization: Bearer a477b3a3366768c07e4c458f518711b4b351e8d2c2f0f78a1524e4d3efd00603
Host: signapi-prep.eparaksts.lv

Response

Binary object

PropertyTypeDescription
File
Binary data
Requested file

Datņu dzēšana

Scope

Delete a file in a file processing session.

Description

The specified file is deleted from the session.

Request

The Service provider's application sends the following GET request using TLS:

DELETE /api-storage/v1.0/{sessionId}/{documentId}
PropertyTypeUsageDescription
sessionId
String (64)MandatoryFile processing session identifier
documentId
String (64)MandatoryDocument identifier, received from "upload" operation as "id" property

Authorization

The request must contain an Authorization header with an OAuth Introspect access token obtained via Integration Platform a Service provider's credentials grant flow.

Introspect piekļuves talona (token) saņemšana

Description

This operation obtains an OAuth 2.0 access token. This operation can be invoked as part of an OAuth 2.0 Service provider's credentials grant flow.

Introspect access token

When the Service provider's credentials grant flow is used, the obtained access token demonstrates the administrative authorization of the Service provider's application making the call for accessing certain resources or services (i.e., without direct intervention of the resource's owner), or for accessing resources of the Service provider's application. Token is issued when the authorization server that processes the request is not associated to an identity provider. A token of this type can be used for accessing resources not associated to end-users or to end-user resources of any domain.

This type of access token is used to get access to Signature creation and validation service API's

Request

To obtain the token, the Service provider's application must send a request like the following to authorization server using TLS. This request is sent directly from the Service provider’s application to authorization server and does not go via the browser.

POST /trustedx-authserver/oauth/{as}/token

Parameter

Title

Type

Field

Description

as

path

mandatory

Use "lvrtc-eipsign-as"

Host:

Test environment: eidas-demo.eparaksts.lv

Production: eidas.eparaksts.lv

Content-Type Header

Content-Type: application/x-www-form-urlencoded; charset=UTF-8


In HTTP POST request is necessary to incorporated the following main attribute: Authorization – API access token.

Authorization: Basic <API-Key>

How to generate API Access Key

Before Service provider access Integration platform API, LVRTC shall register Service provider as customer of Integration platform. After signing a contract with LVRTC (Test of Production environment) LVRTC generates Service Provider’s application identifier – (client_id) and shared secret (client_secret), intended for the customer usage.
API Access Key (API Key) is generated from the Service provider’s application identifier (client_id), a secret shared with the platform (client_secret)  on the following basis:

Service provider's application identifier client_id are converted using the UTF-8 character encoding and URL encoding conditions.

(warning)  For example, value "Portāls" conversion result is "port%C4%81ls".

Service provider's application password client_secret is converted by using the UTF-8 character encoding and URL encoding conditions.

(warning)  For example, value "drošība" conversion result is "dro%C5%A1%C4%ABba".

Both values of the previous two steps must be combined with separator colon “:” between them.

(warning)  For example, by using previous examples, the result will be "port%C4%81ls:dro%C5%A1%C4%ABba".

Obtained value must be converted using base 64 encoding without line breaks.

(warning)  For example, values "port%C4%81ls:dro%C5%A1%C4%ABba" conversion result is "CG94ydCVDNCUMWxzOmRybyVDNSVBMSVDNCVBQmJh".

"MIME Tools" tool in "Notepad + +" can be used for this purpose.

API-Key = base64[url_encode(utf8(<client_id>)) ':' url_encode(utf8(<client_secret>))]

Body

The content of the request for Introspect access token (used for access SignAPI service):

Property

Usage

Description

grant_type

mandatory

Must have the client_credentials value .

scopemandatoryMust have the urn:safelayer:eidas:oauth:token:introspect value

Example (Introspect access token)

The following example shows a situation in which the Service provider’s application with the identifier "Portal" and the password "drošība" authority shall transmit the request to the server with the identifier "lvrtc-eips-as":

POST /trustedx-authserver/oauth/lvrtc-eipsign-as/token HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Authorization: Basic CG94ydCVDNCUMWxzOmRybyVDNSVBMSVDNCVBQmJh
Host: eidas-demo.eparaksts.lv
grant_type=client_credentials&
			scope=urn%3Asafelayer%3Aeidas%3Aoauth%3Atoken%3Aintrospect

Response

In response, Integration platform authorization server issues a bearer-type OAuth 2.0 access token and returns it in a JSON structure.

{
"access_token" : {string}, 
"token_type" : "Bearer", 
"expires_in" : {number}
}

Parameter

PropertyDescription
access_token
Access token generated by Authorization server. The token has the characteristics specified in the configuration of the authorization server that processed the request and consists of a random string of the number of bytes specified in the Access token number of random bytes (by default, 32), encoded in hexadecimal.
token_type
Type of access token. Always has the "bearer" value. (Bearer type OAuth 2.0 access token).
expires_in
Lifetime (in seconds) of the access token. The Service provider’s application must perform the access the token authorizes before the token expires. This value can be configured in the Token timeout option of the authorization server (by default, 120 seconds). Once this timeout has expired, the token becomes invalid, and the Service provider’s application must obtain another one if it wants to continue invoking the protected services.

Example

Introspect access token:

HTTP/1.1 200 OK
Content-Type: application/json;charset=utf-8 
Cache-Control: no-store, no-cache, must-revalidate 
Pragma: no-cache
{
 "scope": "urn:safelayer:eidas:oauth:token:introspect",
 "access_token": "dfffb0d7f90bed142464750cacad5e4b9e23f58ecb1d77e3bdf706ba208ad16a",
 "token_type": "Bearer",
 "expires_in": 600
}



Example

DELETE /api-storage/v1.0/cd6afb8b7e9fd6aa2b2ef7b981fa98cb59128fdef6c064f74dc9cef529a79d17/cc8bcb560bbfee4c190433ea63c549d1
HTTP/1.1
Authorization: Bearer a477b3a3366768c07e4c458f518711b4b351e8d2c2f0f78a1524e4d3efd00603
Host: signapi-prep.eparaksts.lv

Response

JSON object:

{
    "data": "Document {documentId} deleted"
}
PropertyTypeDescription
documentId
String
Document identifier, received from "upload" operation as "id" property

Example

{
    "data": "Document cc8bcb560bbfee4c190433ea63c549d1 deleted"
}






Parakstīšanas API (SignAPI)

Paketes kopsavilkuma aprēķināšanas piemērs

Scope

Provide a signable data value calculation from the signable file by using the end-user signature certificate received.

Description

1. Start signing session. If there are problems with the files or the request does not meet the format requirements for the document signing, the process is terminated and an error is returned;
2. The hash of each file to be signed are calculated as well as signable data;
3. The signature algorithm  is determined from certificate;
4. The prepared signable data in base64 format is returned to the requester for signature.

Request

The Service provider's application sends the following GET request using TLS:

POST /api-sign/v1.0/CalculateDigest 

Authorization

The request must contain an Authorization header with an OAuth Introspect access token obtained via Integration Platform a Service provider's credentials grant flow.

Introspect piekļuves talona (token) saņemšana

Description

This operation obtains an OAuth 2.0 access token. This operation can be invoked as part of an OAuth 2.0 Service provider's credentials grant flow.

Introspect access token

When the Service provider's credentials grant flow is used, the obtained access token demonstrates the administrative authorization of the Service provider's application making the call for accessing certain resources or services (i.e., without direct intervention of the resource's owner), or for accessing resources of the Service provider's application. Token is issued when the authorization server that processes the request is not associated to an identity provider. A token of this type can be used for accessing resources not associated to end-users or to end-user resources of any domain.

This type of access token is used to get access to Signature creation and validation service API's

Request

To obtain the token, the Service provider's application must send a request like the following to authorization server using TLS. This request is sent directly from the Service provider’s application to authorization server and does not go via the browser.

POST /trustedx-authserver/oauth/{as}/token

Parameter

Title

Type

Field

Description

as

path

mandatory

Use "lvrtc-eipsign-as"

Host:

Test environment: eidas-demo.eparaksts.lv

Production: eidas.eparaksts.lv

Content-Type Header

Content-Type: application/x-www-form-urlencoded; charset=UTF-8


In HTTP POST request is necessary to incorporated the following main attribute: Authorization – API access token.

Authorization: Basic <API-Key>

How to generate API Access Key

Before Service provider access Integration platform API, LVRTC shall register Service provider as customer of Integration platform. After signing a contract with LVRTC (Test of Production environment) LVRTC generates Service Provider’s application identifier – (client_id) and shared secret (client_secret), intended for the customer usage.
API Access Key (API Key) is generated from the Service provider’s application identifier (client_id), a secret shared with the platform (client_secret)  on the following basis:

Service provider's application identifier client_id are converted using the UTF-8 character encoding and URL encoding conditions.

(warning)  For example, value "Portāls" conversion result is "port%C4%81ls".

Service provider's application password client_secret is converted by using the UTF-8 character encoding and URL encoding conditions.

(warning)  For example, value "drošība" conversion result is "dro%C5%A1%C4%ABba".

Both values of the previous two steps must be combined with separator colon “:” between them.

(warning)  For example, by using previous examples, the result will be "port%C4%81ls:dro%C5%A1%C4%ABba".

Obtained value must be converted using base 64 encoding without line breaks.

(warning)  For example, values "port%C4%81ls:dro%C5%A1%C4%ABba" conversion result is "CG94ydCVDNCUMWxzOmRybyVDNSVBMSVDNCVBQmJh".

"MIME Tools" tool in "Notepad + +" can be used for this purpose.

API-Key = base64[url_encode(utf8(<client_id>)) ':' url_encode(utf8(<client_secret>))]

Body

The content of the request for Introspect access token (used for access SignAPI service):

Property

Usage

Description

grant_type

mandatory

Must have the client_credentials value .

scopemandatoryMust have the urn:safelayer:eidas:oauth:token:introspect value

Example (Introspect access token)

The following example shows a situation in which the Service provider’s application with the identifier "Portal" and the password "drošība" authority shall transmit the request to the server with the identifier "lvrtc-eips-as":

POST /trustedx-authserver/oauth/lvrtc-eipsign-as/token HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Authorization: Basic CG94ydCVDNCUMWxzOmRybyVDNSVBMSVDNCVBQmJh
Host: eidas-demo.eparaksts.lv
grant_type=client_credentials&
			scope=urn%3Asafelayer%3Aeidas%3Aoauth%3Atoken%3Aintrospect

Response

In response, Integration platform authorization server issues a bearer-type OAuth 2.0 access token and returns it in a JSON structure.

{
"access_token" : {string}, 
"token_type" : "Bearer", 
"expires_in" : {number}
}

Parameter

PropertyDescription
access_token
Access token generated by Authorization server. The token has the characteristics specified in the configuration of the authorization server that processed the request and consists of a random string of the number of bytes specified in the Access token number of random bytes (by default, 32), encoded in hexadecimal.
token_type
Type of access token. Always has the "bearer" value. (Bearer type OAuth 2.0 access token).
expires_in
Lifetime (in seconds) of the access token. The Service provider’s application must perform the access the token authorizes before the token expires. This value can be configured in the Token timeout option of the authorization server (by default, 120 seconds). Once this timeout has expired, the token becomes invalid, and the Service provider’s application must obtain another one if it wants to continue invoking the protected services.

Example

Introspect access token:

HTTP/1.1 200 OK
Content-Type: application/json;charset=utf-8 
Cache-Control: no-store, no-cache, must-revalidate 
Pragma: no-cache
{
 "scope": "urn:safelayer:eidas:oauth:token:introspect",
 "access_token": "dfffb0d7f90bed142464750cacad5e4b9e23f58ecb1d77e3bdf706ba208ad16a",
 "token_type": "Bearer",
 "expires_in": 600
}



Body

{
"sessions":[
    {
      "sessionId": "string"
    }
  ],
  "certificate": "string",
  "signAsPdf": true,
  "createNewEdoc": true
}

PropertyDescription
sessions
Information about file processing sessions
sessions.sessionId
File processing session identifier. It is possible to specify multiple sessions.
certificate
Signing certificate in base64 format
signAsPdf
True - will be signed as PDF (can only be used for signing PDFs and only one PDF file per session). In this case, the propery "createNewEdoc" will be ignored.
False - will create XAdES signature in ASICE container (EDOC).
createNewEdoc

True - Always creates new ASICE container (even if signable file is already a ASICE container - ASICE in the ASICE container);

False - If existing file is ASICE container, new signature will be added within existing ASICE container. If file is not ASICE, it will be added in ASICE container.


Example of single session signing

POST /api-sign/v1.0/CalculateDigest HTTP/1.1
Authorization: Bearer a477b3a3366768c07e4c458f518711b4b351e8d2c2f0f78a1524e4d3efd00603
Host: signapi-prep.eparaksts.lv
{
  "sessions": [
     {
        "sessionId": "fefdaec2b14bf2977d32a861fb49545244c654f7a4736dcc081ae1857a3a3dd4"
     }
  ],
  "certificate": "MIIG/j.......<sign certificate base64 here>.......xFP/IP==",
  "signAsPdf": false,
  "createNewEdoc": false
}

Example of batch session signing

POST /api-signing/v1.0/CalculateDigest HTTP/1.1
Authorization: Bearer a477b3a3366768c07e4c458f518711b4b351e8d2c2f0f78a1524e4d3efd00603
Host: signapi-prep.eparaksts.lv
{
  "sessions": [
          {
                 "sessionId": "fefdaec2b14bf2977d32a861fb49545244c654f7a4736dcc081ae1857a3a3dd4"
          },
          {
                 "sessionId": "fefdaec2b14bf2977d32a861fb49545244c654f7a4736dcc081ae18512121212"
          },
          {
                 "sessionId": "fefdaec2b14bf2977d32a861fb49545244c654f7a4736dcc081ae185bbbbbbbb"
          }
  ],
  "certificate": "MIIG/j.......<sign certificate base64 here>.......xFP/IP==",
  "signAsPdf": false,
  "createNewEdoc": false
}


Response

JSON object:

{
"sessionDigests":[
    {
      "sessionId": "string",
      "digest": "string",
      "error": {
          "code": "string",
          "message": "string"
      }
    }
  ],
  "digests_summary": "string",
  "algorithm": "string"
}

PropertyDescription
sessionDigest
Information about signable data session
sessionDigest.sessionId
File processing session identifier
sessionDigest.diggest

Signable data in base64 format

In case of server signing - received "diggest" property value shall be used (as is, without any reformatting) in Electronic signature provider API when Create a Digital Signature on the Server as "digest_value" property value.

In case of signing with Smart Card by using LVRTC provided browser extension integration, then this value shall be converted to HEX.

sessionDigests.error
Session error if any
sessionDigests.error.code
Session error code
sessionDigests.error.message
Session error message 
digests_summary

(warning) This parameter must only be used to obtain the authorization from the end-user for generating a digital signature with a server signing identity enabled via password stored on the HSM. (warning)

It is already precalculated digest summary. In case of server signing - "digests_summary" property value shall be used (as is, without any reformatting) in OAuth2.0 Authorization API when obtaining authorization code for signing operation as "digests_summary" property value.

algorithm
Algorithm of the digital signature


Example of single session signing

{
   "data": {
       "sessionDigests": [
           {
               "sessionId": "a37e460b4c65cb01a01dce5c58149806ca2d20dab22e99905d45128c4e693a90",
               "digest": "4xZX5G+R4gTbK2r6RlismZw4EBftvbSDcE3lXfpLMM4="
           }
       ],
       "digests_summary": "mnF3XVRWujh/Tsc3oA2HVGl0SI8VNb3pmscMcDhEzDo=",
       "algorithm": "SHA256"
   }
}

Example of batch session signing 

{
  "data": {
          "sessionDigests": [
                 {
                    "sessionId": "fefdaec2b14bf2977d32a861fb49545244c654f7a4736dcc081ae1857a3a3dd4",
                    "digest": "wRX+DNmDdlDrMK8X/MEdersGZbsgTiSFHi26domxjwA="
                 },
                 {
                    "sessionId": "fefdaec2b14bf2977d32a861fb49545244c654f7a4736dcc081ae18512121212",
                    "digest": "wRX+DNmDdlDrMK8X/MEdersGZbsgTiSFHi26domxjwA="
                 },
                 {
                    "sessionId": "fefdaec2b14bf2977d32a861fb49545244c654f7a4736dcc081ae185bbbbbbbb",
                    "digest": "wRX+DNmDdlDrMK8X/MEdersGZbsgTiSFHi26domxjwA="
                 }
           ],
                  "digests_summary": "mnF3XVRWujh/Tsc3oA2HVGl0SI8VNb3pmscMcDhEzDo=",
         "algorithm": "SHA256"
  }
}



Paketes parakstīšanas pabeigšanas piemērs

Scope

Ensure the finalization of the signature or seal (and container in case of ASICE).

Description

1. Attaches a signed data to the document;
2. Starts LVRTC timestamp request;
3. Attach timestamp and the revocation data (for example - OCSP) to the signature;
4. In case of successful execution the message "OK" is returned.

Request

The Service provider's application sends the following GET request using TLS:

POST /api-sign/v1.0/finalizeSigning

Authorization

The request must contain an Authorization header with an OAuth Introspect access token obtained via Integration Platform a Service provider's credentials grant flow.

Introspect piekļuves talona (token) saņemšana

Description

This operation obtains an OAuth 2.0 access token. This operation can be invoked as part of an OAuth 2.0 Service provider's credentials grant flow.

Introspect access token

When the Service provider's credentials grant flow is used, the obtained access token demonstrates the administrative authorization of the Service provider's application making the call for accessing certain resources or services (i.e., without direct intervention of the resource's owner), or for accessing resources of the Service provider's application. Token is issued when the authorization server that processes the request is not associated to an identity provider. A token of this type can be used for accessing resources not associated to end-users or to end-user resources of any domain.

This type of access token is used to get access to Signature creation and validation service API's

Request

To obtain the token, the Service provider's application must send a request like the following to authorization server using TLS. This request is sent directly from the Service provider’s application to authorization server and does not go via the browser.

POST /trustedx-authserver/oauth/{as}/token

Parameter

Title

Type

Field

Description

as

path

mandatory

Use "lvrtc-eipsign-as"

Host:

Test environment: eidas-demo.eparaksts.lv

Production: eidas.eparaksts.lv

Content-Type Header

Content-Type: application/x-www-form-urlencoded; charset=UTF-8


In HTTP POST request is necessary to incorporated the following main attribute: Authorization – API access token.

Authorization: Basic <API-Key>

How to generate API Access Key

Before Service provider access Integration platform API, LVRTC shall register Service provider as customer of Integration platform. After signing a contract with LVRTC (Test of Production environment) LVRTC generates Service Provider’s application identifier – (client_id) and shared secret (client_secret), intended for the customer usage.
API Access Key (API Key) is generated from the Service provider’s application identifier (client_id), a secret shared with the platform (client_secret)  on the following basis:

Service provider's application identifier client_id are converted using the UTF-8 character encoding and URL encoding conditions.

(warning)  For example, value "Portāls" conversion result is "port%C4%81ls".

Service provider's application password client_secret is converted by using the UTF-8 character encoding and URL encoding conditions.

(warning)  For example, value "drošība" conversion result is "dro%C5%A1%C4%ABba".

Both values of the previous two steps must be combined with separator colon “:” between them.

(warning)  For example, by using previous examples, the result will be "port%C4%81ls:dro%C5%A1%C4%ABba".

Obtained value must be converted using base 64 encoding without line breaks.

(warning)  For example, values "port%C4%81ls:dro%C5%A1%C4%ABba" conversion result is "CG94ydCVDNCUMWxzOmRybyVDNSVBMSVDNCVBQmJh".

"MIME Tools" tool in "Notepad + +" can be used for this purpose.

API-Key = base64[url_encode(utf8(<client_id>)) ':' url_encode(utf8(<client_secret>))]

Body

The content of the request for Introspect access token (used for access SignAPI service):

Property

Usage

Description

grant_type

mandatory

Must have the client_credentials value .

scopemandatoryMust have the urn:safelayer:eidas:oauth:token:introspect value

Example (Introspect access token)

The following example shows a situation in which the Service provider’s application with the identifier "Portal" and the password "drošība" authority shall transmit the request to the server with the identifier "lvrtc-eips-as":

POST /trustedx-authserver/oauth/lvrtc-eipsign-as/token HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Authorization: Basic CG94ydCVDNCUMWxzOmRybyVDNSVBMSVDNCVBQmJh
Host: eidas-demo.eparaksts.lv
grant_type=client_credentials&
			scope=urn%3Asafelayer%3Aeidas%3Aoauth%3Atoken%3Aintrospect

Response

In response, Integration platform authorization server issues a bearer-type OAuth 2.0 access token and returns it in a JSON structure.

{
"access_token" : {string}, 
"token_type" : "Bearer", 
"expires_in" : {number}
}

Parameter

PropertyDescription
access_token
Access token generated by Authorization server. The token has the characteristics specified in the configuration of the authorization server that processed the request and consists of a random string of the number of bytes specified in the Access token number of random bytes (by default, 32), encoded in hexadecimal.
token_type
Type of access token. Always has the "bearer" value. (Bearer type OAuth 2.0 access token).
expires_in
Lifetime (in seconds) of the access token. The Service provider’s application must perform the access the token authorizes before the token expires. This value can be configured in the Token timeout option of the authorization server (by default, 120 seconds). Once this timeout has expired, the token becomes invalid, and the Service provider’s application must obtain another one if it wants to continue invoking the protected services.

Example

Introspect access token:

HTTP/1.1 200 OK
Content-Type: application/json;charset=utf-8 
Cache-Control: no-store, no-cache, must-revalidate 
Pragma: no-cache
{
 "scope": "urn:safelayer:eidas:oauth:token:introspect",
 "access_token": "dfffb0d7f90bed142464750cacad5e4b9e23f58ecb1d77e3bdf706ba208ad16a",
 "token_type": "Bearer",
 "expires_in": 600
}



Body

{
"sessionSignatureValues": [
    {
      "sessionId": "string",
      "signatureValue": "string"
    }
  ],
  "authCertificate": "string"
}

PropertyDescription
sessionSignatureValues
Contains details of signed data
sessionSignatureValues.sessionId
File processing session identifier. It is possible to specify multiple sessions.
sessionSignatureValues.signatureValue
Signed data in base64 format. If there is specified multiple sessions, then each specified session shall contain its signed data.
authCertificate
End-user's authentication certificate

Examples

Example for single signature
POST /api-sign/v1.0/finalizeSigning HTTP/1.1
Authorization: Bearer a477b3a3366768c07e4c458f518711b4b351e8d2c2f0f78a1524e4d3efd00603
Host: signapi-prep.eparaksts.lv
{
  "sessionSignatureValues": [
     {
        "sessionId": "76fa04d8e5e2451b867af6ae667558395459fb9d082d31dadb9f22222f80a3d2",
        "signatureValue": "goU+aIw0sZHRwepWiooOdSb0eDbCZcBymXSgsLmYxCr6I6aZdDiG07vp4bbJMtGGPbTKEh6ZR+7eCmNfC02g/hhlGU4OCr+LFhKFIcYqUW1VGvnEPx4eIJlw43pSIo6k/It16RYyYWG1e2DVy1HuMoZEBScUAAN4tHFiHCiIsPuuzIYnRJtZMVi795dvgkEGxnghvzxp0rF+2eoT/5gMKEcBxRIKKs2gWyFK+UIpiXigk0K8LTSEw4XXKDCMSVJ8Vp08nRm1grE0tjLY6tvUVs61Bh5ylC4d7Nh4gQB5VBJHBcng8lFAfXIokX0hD9eoHBrx/bZ7uN1Co5U8H/HFvw=="
     }
  ],
  "authCertificate": "MIIGT....<auth cert base64 here>.......UoKew=="
}
Example for batch signing
POST /api-sign/v1.0/finalizeSigning HTTP/1.1
Authorization: Bearer a477b3a3366768c07e4c458f518711b4b351e8d2c2f0f78a1524e4d3efd00603
Host: signapi-prep.eparaksts.lv
{
  "sessionSignatureValues": [
    {
        "sessionId": "4bf47a3df5020ed537cc6337429db6dcbf7c299ab03474099a0b592190362d06",
        "signatureValue": "BJjtf/DjqBOTyFjjFci+HyzSnzhKE/diYpM9uf3HGLeX4VN+KYzwwgTiTnHn67zDMj5Qouu3ldBeIvswmD/wDuwk+XyMaII7iVEg9CpvABhjDINXhtu5Wn/X5DLXQovN6Fd2xDBV1a392XfeBDtWNmWUr5P6ZZ7wfaCGuae1YyFUbfep6nL/CC6iwKUmVMYyvHzr1ZHSpg/NAVvXC73Q3Bv3/XBYgPusuJZ5Sfv1Xv6PkyOMB9iC5307xk2V3+ptnDnKus+qYQioNhdKSmR4r92tQkZbtK/kgPmkwpGO/B0wmI18ldzVS8gv7Fhorxp0sbDzjRpj0DI+UH6yEZn7ew==" 
     },
     {
        "sessionId": "967e69ed16f7056dfe430f6292fd0f1dd9c28d87379bb7bcef94021ecc096642",
        "signatureValue": "ldH/38RET4fR4nLH5s6/5uzkVbG4GPbsAsL0Wi9fAWWovXaR0ukzdhDnGVNuCQWfulOpEGKyTHvdfqbAKxrGlJ1QKcWvEluqk6bnYqUA/vPOabPpXqWAvhpqf6R507aGCtbsUJ2OoNLyIl3BCP1fqV0uD12bz4x8Geqm2pjB+mj1rbp8kN4og5z4MrPd34Wi0n5JD+pFqd4/UN5ttXB4Px5oZJGw99KvXU8sEDbyxn6qlojn7Z8OAQiwW6+x09degASXKGFHNbLBETbw8K/pUy1eaJDGQDn/+pba7ygCMB4YnK2cl7c7hgvkzQjyYg3PQ5kpwCPiUj4Tt5Zd9u5o5A==" 
     },
     {
        "sessionId": "3d87b13595af5094309028b7482df121988f97f4c04873ffd736a4186dd04069",
        "signatureValue": "fR3E287+05Gb8bPjqoiy0SGMtbKLGkopMb+AUgpS872bJ6qctEmpmZ5ZcsQ5j6HjmsZG34qg7Cvj/AuviOEK8XPDrlFtGeHeq5Lb5Kjv7FJbDqoAP+DrRLmtt49/g9tSEbplZAiLiRCQg6uHpMr3gP7Jv6YWsQINArkAB7Gkpy/0eA5egaabxmP78iz8Y74XGl2eBbkUmJCXyOPUTsPmkJZuzVMVIG5GFBoDz32AVUC0S2J5jOW8WUu/JPIeD/UqAE7Rs4c0jKz6PnjbZLFKRE/qk2j2PCjzgd6kKNkNgPCA1mXXTPAd95Rq0FK25ZeHfZW93AaHDV1OFq85J6kMdA==" 
     }
  ],
  "authCertificate": "MIIGT......<auth cert base64 here>........UoKew=="
}

Response

JSON object:

{
    "data": {
        "results": [
            {
                "sessionId": "string"
            }
        ]
    }
}

Property
Type
Description
sessionIdString (64)

File processing session identifier.

Example for single signature

{
    "data": {
        "results": [
            {
                "sessionId": "2ddec3e17a456417f48b044d71d2db2a31d00b62baea3de1211617e856f0f19d"
            }
        ]
    }
}

Example for batch signing

{
    "data": {
        "results": [
            {
                "sessionId": "4bf47a3df5020ed537cc6337429db6dcbf7c299ab03474099a0b592190362d06"
            },
            {
                "sessionId": "967e69ed16f7056dfe430f6292fd0f1dd9c28d87379bb7bcef94021ecc096642"
            },
            {
                "sessionId": "3d87b13595af5094309028b7482df121988f97f4c04873ffd736a4186dd04069"
            }
        ]
    }
}



Arhīva laika zīmoga pieprasījums

Scope

Provide a archive time stamp to already signed document.

Description

  1. Requests time stamp with using client authentication certificate;
  2. Received archive time stamp is added to signature with "ARCHIVE_TIMESTAMP" type;
  3. In case of successful execution the session unique identifier is returned.

Request

The Service provider's application sends the following POST request using TLS:

POST /api-sign/v1.0/addArchive

Authorization

The request must contain an Authorization header with an OAuth Introspect access token obtained via Integration Platform a Service provider's credentials grant flow.

Introspect piekļuves talona (token) saņemšana

Description

This operation obtains an OAuth 2.0 access token. This operation can be invoked as part of an OAuth 2.0 Service provider's credentials grant flow.

Introspect access token

When the Service provider's credentials grant flow is used, the obtained access token demonstrates the administrative authorization of the Service provider's application making the call for accessing certain resources or services (i.e., without direct intervention of the resource's owner), or for accessing resources of the Service provider's application. Token is issued when the authorization server that processes the request is not associated to an identity provider. A token of this type can be used for accessing resources not associated to end-users or to end-user resources of any domain.

This type of access token is used to get access to Signature creation and validation service API's

Request

To obtain the token, the Service provider's application must send a request like the following to authorization server using TLS. This request is sent directly from the Service provider’s application to authorization server and does not go via the browser.

POST /trustedx-authserver/oauth/{as}/token

Parameter

Title

Type

Field

Description

as

path

mandatory

Use "lvrtc-eipsign-as"

Host:

Test environment: eidas-demo.eparaksts.lv

Production: eidas.eparaksts.lv

Content-Type Header

Content-Type: application/x-www-form-urlencoded; charset=UTF-8


In HTTP POST request is necessary to incorporated the following main attribute: Authorization – API access token.

Authorization: Basic <API-Key>

How to generate API Access Key

Before Service provider access Integration platform API, LVRTC shall register Service provider as customer of Integration platform. After signing a contract with LVRTC (Test of Production environment) LVRTC generates Service Provider’s application identifier – (client_id) and shared secret (client_secret), intended for the customer usage.
API Access Key (API Key) is generated from the Service provider’s application identifier (client_id), a secret shared with the platform (client_secret)  on the following basis:

Service provider's application identifier client_id are converted using the UTF-8 character encoding and URL encoding conditions.

(warning)  For example, value "Portāls" conversion result is "port%C4%81ls".

Service provider's application password client_secret is converted by using the UTF-8 character encoding and URL encoding conditions.

(warning)  For example, value "drošība" conversion result is "dro%C5%A1%C4%ABba".

Both values of the previous two steps must be combined with separator colon “:” between them.

(warning)  For example, by using previous examples, the result will be "port%C4%81ls:dro%C5%A1%C4%ABba".

Obtained value must be converted using base 64 encoding without line breaks.

(warning)  For example, values "port%C4%81ls:dro%C5%A1%C4%ABba" conversion result is "CG94ydCVDNCUMWxzOmRybyVDNSVBMSVDNCVBQmJh".

"MIME Tools" tool in "Notepad + +" can be used for this purpose.

API-Key = base64[url_encode(utf8(<client_id>)) ':' url_encode(utf8(<client_secret>))]

Body

The content of the request for Introspect access token (used for access SignAPI service):

Property

Usage

Description

grant_type

mandatory

Must have the client_credentials value .

scopemandatoryMust have the urn:safelayer:eidas:oauth:token:introspect value

Example (Introspect access token)

The following example shows a situation in which the Service provider’s application with the identifier "Portal" and the password "drošība" authority shall transmit the request to the server with the identifier "lvrtc-eips-as":

POST /trustedx-authserver/oauth/lvrtc-eipsign-as/token HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Authorization: Basic CG94ydCVDNCUMWxzOmRybyVDNSVBMSVDNCVBQmJh
Host: eidas-demo.eparaksts.lv
grant_type=client_credentials&
			scope=urn%3Asafelayer%3Aeidas%3Aoauth%3Atoken%3Aintrospect

Response

In response, Integration platform authorization server issues a bearer-type OAuth 2.0 access token and returns it in a JSON structure.

{
"access_token" : {string}, 
"token_type" : "Bearer", 
"expires_in" : {number}
}

Parameter

PropertyDescription
access_token
Access token generated by Authorization server. The token has the characteristics specified in the configuration of the authorization server that processed the request and consists of a random string of the number of bytes specified in the Access token number of random bytes (by default, 32), encoded in hexadecimal.
token_type
Type of access token. Always has the "bearer" value. (Bearer type OAuth 2.0 access token).
expires_in
Lifetime (in seconds) of the access token. The Service provider’s application must perform the access the token authorizes before the token expires. This value can be configured in the Token timeout option of the authorization server (by default, 120 seconds). Once this timeout has expired, the token becomes invalid, and the Service provider’s application must obtain another one if it wants to continue invoking the protected services.

Example

Introspect access token:

HTTP/1.1 200 OK
Content-Type: application/json;charset=utf-8 
Cache-Control: no-store, no-cache, must-revalidate 
Pragma: no-cache
{
 "scope": "urn:safelayer:eidas:oauth:token:introspect",
 "access_token": "dfffb0d7f90bed142464750cacad5e4b9e23f58ecb1d77e3bdf706ba208ad16a",
 "token_type": "Bearer",
 "expires_in": 600
}



Body

{
  "sessions": [
    {
      "sessionId": "{String}"
    }
  ],
  "authCertificate": "{String}"
}
PropertyDescription
sessionId
File processing session identifier
authCertificate
End-user's authentication certificate

Example

POST /api-sign/v1.0/addArchive HTTP/1.1
Authorization: Bearer a477b3a3366768c07e4c458f518711b4b351e8d2c2f0f78a1524e4d3efd00603
Host: signapi-prep.eparaksts.lv
{
  "sessions": [
    {
      "sessionId": "26ae33853f7df73eaa84346a04a188db1614305aee43de0da667c67a4d371490"
    }
  ],
  "authCertificate": "MIIGTjCCBDagAwIBAgIQGd6hCV2AEjVdTWDw5EEurDANBgkqhkiG9w0BAQsFADCBgzELMAkGA1UEBhMCTFYxOTA3BgNVBAoMMFZBUyBMYXR2aWphcyBWYWxzdHMgcmFkaW8gdW4gdGVsZXbEq3ppamFzIGNlbnRyczEaMBgGA1UEYQwRTlRSTFYtNDAwMDMwMTEyMDMxHTAbBgNVBAMMFERFTU8gTFYgZUlEIElDQSAyMDE3MB4XDTE5MDgwOTEyMDI1NloXDTIyMDgwOTEyMDI1NlowcDELMAkGA1UEBhMCTFYxHDAaBgNVBAMME0FORFJJUyBQQVJBVURaScWFxaAxFTATBgNVBAQMDFBBUkFVRFpJxYXFoDEPMA0GA1UEKgwGQU5EUklTMRswGQYDVQQFExJQTk9MVi0zMjEyMTUtNzkxNTkwggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQCS0tRy5CYE8Bz0yWmCIftJ0AIBHCvCW68AJPRmcJRNB0lCmXJoJvNKt9jnsgXLzUCgylK4hb5BmpbMP8Pt1TB2IIBNYIg/MdiwwAiAJi9OChCdJrlj0tpbZO3WPlTr3TjihsYxjvImCEwciPWXGV+Y5FJSnfnlMgZ22SMdiGRT5rrZ0v122+ULfVqMJc5s/Fufws3vXuNRBewuzlCM6dcRmwl05qr0/Y7rPVR57kId+2dZD/lWB0aXUE320Cr3u2J0y5iXS4zKUpNrrMozWXinVqhdpdF1l8BM6Kti99Kw1MyEADaRa8hNfyNEAoucjEj2OBuLEP1myII/Xnoj3/yxAgMBAAGjggHOMIIByjAMBgNVHRMBAf8EAjAAMA4GA1UdDwEB/wQEAwIHgDATBgNVHSUEDDAKBggrBgEFBQcDAjAdBgNVHQ4EFgQUppUtW5WAE82oSZPmnak+Y9394CQwHwYDVR0jBBgwFoAUj2jOvOLHQCFTCUK75Z4djEvNvTgwgYsGA1UdIASBgzCBgDA7BgYEAI96AQEwMTAvBggrBgEFBQcCARYjaHR0cHM6Ly93d3cuZXBhcmFrc3RzLmx2L3JlcG9zaXRvcnkwQQYMKwYBBAGB+j0CAQMBMDEwLwYIKwYBBQUHAgEWI2h0dHBzOi8vd3d3LmVwYXJha3N0cy5sdi9yZXBvc2l0b3J5MH0GCCsGAQUFBwEBBHEwbzBCBggrBgEFBQcwAoY2aHR0cDovL2RlbW8uZXBhcmFrc3RzLmx2L2NlcnQvZGVtb19MVl9lSURfSUNBXzIwMTcuY3J0MCkGCCsGAQUFBzABhh1odHRwOi8vb2NzcC5wcmVwLmVwYXJha3N0cy5sdjBIBgNVHR8EQTA/MD2gO6A5hjdodHRwOi8vZGVtby5lcGFyYWtzdHMubHYvY3JsL2RlbW9fTFZfZUlEX0lDQV8yMDE3XzguY3JsMA0GCSqGSIb3DQEBCwUAA4ICAQBkgLwrpoAIx6FVE1NKdoTntzyQBi04+0uBnJdVOs6Zf9AHnZJQon88aorZEqPc0Y4D2/DRQ58EhsEwULN8Us8zfdnd2QM6wpHsHTfzP0+moDLebRJQwzItsN+CiJxvziX7OVIXiS/mNL28mQL4mIW5bh4fbmx/34Dp6b+/sTjaQUmTxyQUWI/FY8rQFiZs/Mp8B1PC6xbnUuYlcsiwesdGapG2WwGF1orVehMnpPQbwB3ZY6JkD/vrrkqJnj8FwHRUYpswSDnmqZJPYTfiK5OoMc9yolH31r+m5h6DD3YkSnfKoxvrfRHQ8//+MWlWH+0W74ZPCNnRwKgAERmAL/3fagWvpSnBPeWy+K/dhfGPyLKKLH/xJrU7FZ0VHTjOtbTIvXorVMX5Ab0aWqv+xOuemKPFD5nzMCBUudXJan0a22RfbWaLm0NUvb/Oz+BN+NcRNc8wKs1Jr3asxNh5F7gxzqMHrxoK6zqCHRvUHPwlwYrGeu3j2vGgE5zinSQi9dBCSsFu7YEh2XZT1r7/4kMjolWX7wSafqO/Zuj/15LNLmsaOIwgDoOfu0VL/WyjN6mWZyJ9RNG9uBYFJSX+jOpAU6g1eIU7cdKydPMCyTjvGSMvfGZ2/3J1ggvdQm7uO93PJyu9V/D5raLXm4tPnIng9/VRc8SSdFcdks4PjUoKew=="
}

Response

JSON object:

{
    "data": {
        "results": [
            {
                "sessionId": {String}
            }
        ]
    }
}
PropertyDescription
sessionId
File processing session identifier

Example

{
    "data": {
        "results": [
            {
                "sessionId": "26ae33853f7df73eaa84346a04a188db1614305aee43de0da667c67a4d371490"
            }
        ]
    }
}

eZīmoga izveidošana

Scope

Puts organization’s electronic seal on a file.

Description

Creates electronic seal signature using organization’s electronic seal certificate, timestamp using authentication certificate and the revocation data (for example - OCSP). 

Request

The Service provider's application sends the following POST request using TLS:

POST /api-sign/v1.0/eSealCreate 

Authorization

The request must contain an Authorization header with an OAuth Introspect access token obtained via Integration Platform a Service provider's credentials grant flow.

Introspect piekļuves talona (token) saņemšana

Description

This operation obtains an OAuth 2.0 access token. This operation can be invoked as part of an OAuth 2.0 Service provider's credentials grant flow.

Introspect access token

When the Service provider's credentials grant flow is used, the obtained access token demonstrates the administrative authorization of the Service provider's application making the call for accessing certain resources or services (i.e., without direct intervention of the resource's owner), or for accessing resources of the Service provider's application. Token is issued when the authorization server that processes the request is not associated to an identity provider. A token of this type can be used for accessing resources not associated to end-users or to end-user resources of any domain.

This type of access token is used to get access to Signature creation and validation service API's

Request

To obtain the token, the Service provider's application must send a request like the following to authorization server using TLS. This request is sent directly from the Service provider’s application to authorization server and does not go via the browser.

POST /trustedx-authserver/oauth/{as}/token

Parameter

Title

Type

Field

Description

as

path

mandatory

Use "lvrtc-eipsign-as"

Host:

Test environment: eidas-demo.eparaksts.lv

Production: eidas.eparaksts.lv

Content-Type Header

Content-Type: application/x-www-form-urlencoded; charset=UTF-8


In HTTP POST request is necessary to incorporated the following main attribute: Authorization – API access token.

Authorization: Basic <API-Key>

How to generate API Access Key

Before Service provider access Integration platform API, LVRTC shall register Service provider as customer of Integration platform. After signing a contract with LVRTC (Test of Production environment) LVRTC generates Service Provider’s application identifier – (client_id) and shared secret (client_secret), intended for the customer usage.
API Access Key (API Key) is generated from the Service provider’s application identifier (client_id), a secret shared with the platform (client_secret)  on the following basis:

Service provider's application identifier client_id are converted using the UTF-8 character encoding and URL encoding conditions.

(warning)  For example, value "Portāls" conversion result is "port%C4%81ls".

Service provider's application password client_secret is converted by using the UTF-8 character encoding and URL encoding conditions.

(warning)  For example, value "drošība" conversion result is "dro%C5%A1%C4%ABba".

Both values of the previous two steps must be combined with separator colon “:” between them.

(warning)  For example, by using previous examples, the result will be "port%C4%81ls:dro%C5%A1%C4%ABba".

Obtained value must be converted using base 64 encoding without line breaks.

(warning)  For example, values "port%C4%81ls:dro%C5%A1%C4%ABba" conversion result is "CG94ydCVDNCUMWxzOmRybyVDNSVBMSVDNCVBQmJh".

"MIME Tools" tool in "Notepad + +" can be used for this purpose.

API-Key = base64[url_encode(utf8(<client_id>)) ':' url_encode(utf8(<client_secret>))]

Body

The content of the request for Introspect access token (used for access SignAPI service):

Property

Usage

Description

grant_type

mandatory

Must have the client_credentials value .

scopemandatoryMust have the urn:safelayer:eidas:oauth:token:introspect value

Example (Introspect access token)

The following example shows a situation in which the Service provider’s application with the identifier "Portal" and the password "drošība" authority shall transmit the request to the server with the identifier "lvrtc-eips-as":

POST /trustedx-authserver/oauth/lvrtc-eipsign-as/token HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Authorization: Basic CG94ydCVDNCUMWxzOmRybyVDNSVBMSVDNCVBQmJh
Host: eidas-demo.eparaksts.lv
grant_type=client_credentials&
			scope=urn%3Asafelayer%3Aeidas%3Aoauth%3Atoken%3Aintrospect

Response

In response, Integration platform authorization server issues a bearer-type OAuth 2.0 access token and returns it in a JSON structure.

{
"access_token" : {string}, 
"token_type" : "Bearer", 
"expires_in" : {number}
}

Parameter

PropertyDescription
access_token
Access token generated by Authorization server. The token has the characteristics specified in the configuration of the authorization server that processed the request and consists of a random string of the number of bytes specified in the Access token number of random bytes (by default, 32), encoded in hexadecimal.
token_type
Type of access token. Always has the "bearer" value. (Bearer type OAuth 2.0 access token).
expires_in
Lifetime (in seconds) of the access token. The Service provider’s application must perform the access the token authorizes before the token expires. This value can be configured in the Token timeout option of the authorization server (by default, 120 seconds). Once this timeout has expired, the token becomes invalid, and the Service provider’s application must obtain another one if it wants to continue invoking the protected services.

Example

Introspect access token:

HTTP/1.1 200 OK
Content-Type: application/json;charset=utf-8 
Cache-Control: no-store, no-cache, must-revalidate 
Pragma: no-cache
{
 "scope": "urn:safelayer:eidas:oauth:token:introspect",
 "access_token": "dfffb0d7f90bed142464750cacad5e4b9e23f58ecb1d77e3bdf706ba208ad16a",
 "token_type": "Bearer",
 "expires_in": 600
}



Body

{
  "sessions": [
    {
      "sessionId": "string"
    }
  ],
  "signAsPdf": false,
  "createNewEdoc": false,
  "signKey": "string",
  "signKeyPassword": "string",
  "authCertificate": "string"
}


PropertyDescription
sessionId

File processing session identifier

Multiple sessions can be sealed at once

signAsPdf

True - will be signed as PDF

False - will cerate XAdES signature in ASICE container (EDOC).

createNewEdoc

True - Always creates new ASICE container (even if signable file is already a ASICE container - ASICE in the ASICE container);

False - If existing file is ASICE container, new signature will be added within existing ASICE container.
signKey
eSeal certificate key in PFX file format encoded in base64.
signKeyPassword

eSeal certificate key password encrypted with API central authentication certificate (issued by LVRTC) public key encoded in base64

RSA Encryption with SHA1 padding

authCertificate
Authentication certificate related to eSeal for Timestamp request in PEM format

Key shall be provided in "pfx" format

Encription

byte[] signKeyPasswordBytes = Encoding.UTF8.GetBytes(req.SignKeyPassword);
byte[] signKeyPasswordBytesEncrypted = publicKey.Encrypt(signKeyPasswordBytes, RSAEncryptionPadding.Pkcs1);
req.SignKeyPassword = Convert.ToBase64String(signKeyPasswordBytesEncrypted);

Example

POST /api-sign/v1.0/eSealCreate  HTTP/1.1
Authorization: Bearer a477b3a3366768c07e4c458f518711b4b351e8d2c2f0f78a1524e4d3efd00603
Host: signapi-prep.eparaksts.lv
{
  "sessions": [
     {
        "sessionId": "702e9106e3fe2987d04a0bf7d585050477c1c0dce4d5b76fafc1178b537bc891"
     }
  ],
  "signAsPdf": false,
  "createNewEdoc": false,
  "signKey": "gbfb43564/70OeyYmqoLJ+YAU1kl+vwGVHT0L+ywky80EO8qx/kMZ7hq1Rm9p/SjzexaS0lIH4yf0OJ74BdZCRGaeBfjZWHiQxBdQSXyeuCqDgawbcOjNMjQeLUK5s4a6T17WXjsPTqPulu8mdyhV+tPhwUE/UdtOcSrJeY+ZkGMsn1i+YcNk1cg12+A/zQZ8lWach7M7Fj7gYhNaHiNW5JUREJKGgVKU4rSEE1T2LosJ9H/b+I3Fj0AVR3Cw57W+VSxn8bXqQG8kq+MWdeomaprRvFQoSwY+MFUedqXgVNOioO8lARJNcd2duMLiy4PKEheqq6rZFftSlYulv+o9nPsbZXMO7H",
  "signKeyPassword": "6hCV2AEjVdTWDw5EEurDANBgkqhkiG9w0BAQsFADCBgzELMAkGA1UEBhM",
   "authCertificate": "MIIGTjCCBDagAwIBAgIQGd6hCV2AEjVdTWDw5EEurDANBgkqhkiG9w0BAQsFADCBgzELMAkGA1UEBhMCTFYxOTA3BgNVBAoMMFZBUyBMYXR2aWphcyBWYWxzdHMgcmFkaW8gdW4gdGVsZXbEq3ppamFzIGNlbnRyczEaMBgGA1UEYQwRTlRSTFYtNDAwMDMwMTEyMDMxHTAbBgNVBAMMFERFTU8gTFYgZUlEIElDQSAyMDE3MB4XDTE5MDgwOTEyMDI1NloXDTIyMDgwOTEyMDI1NlowcDELMAkGA1UEBhMCTFYxHDAaBgNVBAMME0FORFJJUyBQQVJBVURaScWFxaAxFTATBgNVBAQMDFBBUkFVRFpJxYXFoDEPMA0GA1UEKgwGQU5EUklTMRswGQYDVQQFExJQTk9MVi0zMjEyMTUtNzkxNTkwggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQCS0tRy5CYE8Bz0yWmCIftJ0AIBHCvCW68AJPRmcJRNB0lCmXJoJvNKt9jnsgXLzUCgylK4hb5BmpbMP8Pt1TB2IIBNYIg/MdiwwAiAJi9OChCdJrlj0tpbZO3WPlTr3TjihsYxjvImCEwciPWXGV+Y5FJSnfnlMgZ22SMdiGRT5rrZ0v122+ULfVqMJc5s/Fufws3vXuNRBewuzlCM6dcRmwl05qr0/Y7rPVR57kId+2dZD/lWB0aXUE320Cr3u2J0y5iXS4zKUpNrrMozWXinVqhdpdF1l8BM6Kti99Kw1MyEADaRa8hNfyNEAoucjEj2OBuLEP1myII/Xnoj3/yxAgMBAAGjggHOMIIByjAMBgNVHRMBAf8EAjAAMA4GA1UdDwEB/wQEAwIHgDATBgNVHSUEDDAKBggrBgEFBQcDAjAdBgNVHQ4EFgQUppUtW5WAE82oSZPmnak+Y9394CQwHwYDVR0jBBgwFoAUj2jOvOLHQCFTCUK75Z4djEvNvTgwgYsGA1UdIASBgzCBgDA7BgYEAI96AQEwMTAvBggrBgEFBQcCARYjaHR0cHM6Ly93d3cuZXBhcmFrc3RzLmx2L3JlcG9zaXRvcnkwQQYMKwYBBAGB+j0CAQMBMDEwLwYIKwYBBQUHAgEWI2h0dHBzOi8vd3d3LmVwYXJha3N0cy5sdi9yZXBvc2l0b3J5MH0GCCsGAQUFBwEBBHEwbzBCBggrBgEFBQcwAoY2aHR0cDovL2RlbW8uZXBhcmFrc3RzLmx2L2NlcnQvZGVtb19MVl9lSURfSUNBXzIwMTcuY3J0MCkGCCsGAQUFBzABhh1odHRwOi8vb2NzcC5wcmVwLmVwYXJha3N0cy5sdjBIBgNVHR8EQTA/MD2gO6A5hjdodHRwOi8vZGVtby5lcGFyYWtzdHMubHYvY3JsL2RlbW9fTFZfZUlEX0lDQV8yMDE3XzguY3JsMA0GCSqGSIb3DQEBCwUAA4ICAQBkgLwrpoAIx6FVE1NKdoTntzyQBi04+0uBnJdVOs6Zf9AHnZJQon88aorZEqPc0Y4D2/DRQ58EhsEwULN8Us8zfdnd2QM6wpHsHTfzP0+moDLebRJQwzItsN+CiJxvziX7OVIXiS/mNL28mQL4mIW5bh4fbmx/34Dp6b+/sTjaQUmTxyQUWI/FY8rQFiZs/Mp8B1PC6xbnUuYlcsiwesdGapG2WwGF1orVehMnpPQbwB3ZY6JkD/vrrkqJnj8FwHRUYpswSDnmqZJPYTfiK5OoMc9yolH31r+m5h6DD3YkSnfKoxvrfRHQ8//+MWlWH+0W74ZPCNnRwKgAERmAL/3fagWvpSnBPeWy+K/dhfGPyLKKLH/xJrU7FZ0VHTjOtbTIvXorVMX5Ab0aWqv+xOuemKPFD5nzMCBUudXJan0a22RfbWaLm0NUvb/Oz+BN+NcRNc8wKs1Jr3asxNh5F7gxzqMHrxoK6zqCHRvUHPwlwYrGeu3j2vGgE5zinSQi9dBCSsFu7YEh2XZT1r7/4kMjolWX7wSafqO/Zuj/15LNLmsaOIwgDoOfu0VL/WyjN6mWZyJ9RNG9uBYFJSX+jOpAU6g1eIU7cdKydPMCyTjvGSMvfGZ2/3J1ggvdQm7uO93PJyu9V/D5raLXm4tPnIng9/VRc8SSdFcdks4PjUoKew=="}

Response

JSON object:

{
    "results": "string"[
        {
            "sessionId": "string",
            "error": {
                "code": "string",
                "message": "string"
            }
        }
    ]
}
PropertyDescription
results
Signing results: success if error == null or omitted
results.sessionId
File processing session identifier
results.error
Session error if any
results.error.code
Session error code
results.error.message
Session error message

Example

{
  "data": {
	 "results": [
		{
		   "sessionId": "76fa04d8e5e2451b867af6ae667558395459fb9d082d31dadb9f22222f80a3d2"
		}
	 ]
  }
}



Validācijas API

Scope

To receive validation data of signed document.

Descriprion

1. Validation information is returned for the specified file;
2. If the file is not signed, an error message is returned;

Request

The Service provider's application sends the following GET request using TLS:

GET /api-validation/v1.0/{sessionId}/{documentId}/validate
Property
Type
Usage
Description
sessionId
String (64)MandatoryFile processing session identifier
documentId
String (64)MandatoryDocument identifier, received from "upload" or "list" operation as "id" property

Authorization

The request must contain an Authorization header with an OAuth Introspect access token obtained via Integration Platform a Service provider's credentials grant flow.

Introspect piekļuves talona (token) saņemšana

Description

This operation obtains an OAuth 2.0 access token. This operation can be invoked as part of an OAuth 2.0 Service provider's credentials grant flow.

Introspect access token

When the Service provider's credentials grant flow is used, the obtained access token demonstrates the administrative authorization of the Service provider's application making the call for accessing certain resources or services (i.e., without direct intervention of the resource's owner), or for accessing resources of the Service provider's application. Token is issued when the authorization server that processes the request is not associated to an identity provider. A token of this type can be used for accessing resources not associated to end-users or to end-user resources of any domain.

This type of access token is used to get access to Signature creation and validation service API's

Request

To obtain the token, the Service provider's application must send a request like the following to authorization server using TLS. This request is sent directly from the Service provider’s application to authorization server and does not go via the browser.

POST /trustedx-authserver/oauth/{as}/token

Parameter

Title

Type

Field

Description

as

path

mandatory

Use "lvrtc-eipsign-as"

Host:

Test environment: eidas-demo.eparaksts.lv

Production: eidas.eparaksts.lv

Content-Type Header

Content-Type: application/x-www-form-urlencoded; charset=UTF-8


In HTTP POST request is necessary to incorporated the following main attribute: Authorization – API access token.

Authorization: Basic <API-Key>

How to generate API Access Key

Before Service provider access Integration platform API, LVRTC shall register Service provider as customer of Integration platform. After signing a contract with LVRTC (Test of Production environment) LVRTC generates Service Provider’s application identifier – (client_id) and shared secret (client_secret), intended for the customer usage.
API Access Key (API Key) is generated from the Service provider’s application identifier (client_id), a secret shared with the platform (client_secret)  on the following basis:

Service provider's application identifier client_id are converted using the UTF-8 character encoding and URL encoding conditions.

(warning)  For example, value "Portāls" conversion result is "port%C4%81ls".

Service provider's application password client_secret is converted by using the UTF-8 character encoding and URL encoding conditions.

(warning)  For example, value "drošība" conversion result is "dro%C5%A1%C4%ABba".

Both values of the previous two steps must be combined with separator colon “:” between them.

(warning)  For example, by using previous examples, the result will be "port%C4%81ls:dro%C5%A1%C4%ABba".

Obtained value must be converted using base 64 encoding without line breaks.

(warning)  For example, values "port%C4%81ls:dro%C5%A1%C4%ABba" conversion result is "CG94ydCVDNCUMWxzOmRybyVDNSVBMSVDNCVBQmJh".

"MIME Tools" tool in "Notepad + +" can be used for this purpose.

API-Key = base64[url_encode(utf8(<client_id>)) ':' url_encode(utf8(<client_secret>))]

Body

The content of the request for Introspect access token (used for access SignAPI service):

Property

Usage

Description

grant_type

mandatory

Must have the client_credentials value .

scopemandatoryMust have the urn:safelayer:eidas:oauth:token:introspect value

Example (Introspect access token)

The following example shows a situation in which the Service provider’s application with the identifier "Portal" and the password "drošība" authority shall transmit the request to the server with the identifier "lvrtc-eips-as":

POST /trustedx-authserver/oauth/lvrtc-eipsign-as/token HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Authorization: Basic CG94ydCVDNCUMWxzOmRybyVDNSVBMSVDNCVBQmJh
Host: eidas-demo.eparaksts.lv
grant_type=client_credentials&
			scope=urn%3Asafelayer%3Aeidas%3Aoauth%3Atoken%3Aintrospect

Response

In response, Integration platform authorization server issues a bearer-type OAuth 2.0 access token and returns it in a JSON structure.

{
"access_token" : {string}, 
"token_type" : "Bearer", 
"expires_in" : {number}
}

Parameter

PropertyDescription
access_token
Access token generated by Authorization server. The token has the characteristics specified in the configuration of the authorization server that processed the request and consists of a random string of the number of bytes specified in the Access token number of random bytes (by default, 32), encoded in hexadecimal.
token_type
Type of access token. Always has the "bearer" value. (Bearer type OAuth 2.0 access token).
expires_in
Lifetime (in seconds) of the access token. The Service provider’s application must perform the access the token authorizes before the token expires. This value can be configured in the Token timeout option of the authorization server (by default, 120 seconds). Once this timeout has expired, the token becomes invalid, and the Service provider’s application must obtain another one if it wants to continue invoking the protected services.

Example

Introspect access token:

HTTP/1.1 200 OK
Content-Type: application/json;charset=utf-8 
Cache-Control: no-store, no-cache, must-revalidate 
Pragma: no-cache
{
 "scope": "urn:safelayer:eidas:oauth:token:introspect",
 "access_token": "dfffb0d7f90bed142464750cacad5e4b9e23f58ecb1d77e3bdf706ba208ad16a",
 "token_type": "Bearer",
 "expires_in": 600
}



Example

GET /api-validation/v1.0/965af52843d969ab6011c6ba8effbdc307e26517280566ce18a807f37a9029aa/c97823faa1a54658e75207e1a791da2c/validate HTTP/1.1
Authorization: Bearer a477b3a3366768c07e4c458f518711b4b351e8d2c2f0f78a1524e4d3efd00603
Host: signapi-prep.eparaksts.lv

Response

General structure of validation response (JSON object):

{
    "data": {
        "includedFiles": [
            {
                "filename": {String}
            }
        ],
        "signatureForm": {String},
        "signaturesExt": [
            {
                "id": {String},
                "info": {
                    "bestSignatureTime": {Datetime},
					"timestampCreationTime": {Datetime},
					"ocspResponseCreationTime": {Datetime},
					"timeAssertionMessageImprint": {String},
					"signingReason": {String},
					"signerRole": [
						{
							"claimedRole": {String}
						}
					],
					"signatureProductionPlace": {
						"countryName": {String},
						"stateOrProvince": {String},
						"city": {String},
						"postalCode": {String}
					}
                },
                "errors": [
                    {
                        "content": {String}
                    }
                ],
                "signedBy": {String},
                "warnings": [
                    {
                        "content": {String}
                    }
                ],
                "indication": {String},
				"subIndication": {String},
                "signatureLevel": {String},
                "signatureFormat": {String},
                "signerSerialNumber": {String},
				"registrationNumber": {String}
            }
        ],
        "validationTime": {Datetime},
        "signaturesCount": {Number},
        "validationLevel": {String},
        "validatedDocument": {
            "filename": {String}
        },
        "validSignaturesCount": {Number}
    }
}

Property
Description
includedFiles
ArrayInformation about files included in the ASIC container.
includedFiles.filename
StringName of the faile included in the ASIC container.
signatureForm
StringFormat (and optionally version) of the digitally signed document container.
signaturesExt
ArrayCollection of signatures found in digitally signed document
signaturesExt.id
StringSignature ID attribute
signaturesExt.info
ObjectObject containing trusted signing time information.
signaturesExt.info.bestSignatureTime
Date

Time value that is regarded as trusted signing time, denoting the earliest time when it can be trusted by the validation application (because proven by some Proof-of-Existence present in the signature) that a signature has existed.

The source of the value depends on the signature profile (see also SignatureFormat parameter):

- Signature with time-mark (LT_TM level) - the producedAt value of the earliest valid time-mark (OCSP confirmation of the signer's certificate) in the signature.

- Signature with time-stamp (LT or LTA level) - the genTime value of the earliest valid signature time-stamp token in the signature.

- Signature with BES or EPES level - the value is empty, i.e. there is no trusted signing time value available.

signaturesExt.signedBy
StringSignature/Seal Creator. CN (common name) value portion in signer's certificate's subject distinguished name
signaturesExt.errors
ArrayInformation about validation error(s), array of error messages.
signaturesExt.warnings
ArrayBlock of validation warnings that do not affect the overall validation result.
signaturesExt.indication
String

Overall result of the signature's validation process, according to ETSI EN 319 102-1 "Table 5: Status indications of the signature validation process".

Note that the validation results of different signatures in one signed document (signature container) may vary.

Possible values:

TOTAL-PASSED

TOTAL-FAILED

INDETERMINATE

signaturesExt.subindicationStringAdditional subindication in case of failed or indeterminate validation result, according to ETSI EN 319 102-1 "Table 6: Validation Report Structure and Semantics"
signaturesExt.signatureLevel
String

Legal level of the signature, according to Regulation (EU) No 910/2014.

- Possible values on positive validation result:

QESIG

QESEAL

QES

QES_EDL - "ADES_QC" signature, which according to Latvian Electronic Documents Law is equivalent to a handwritten signature

ADESIG_QC

ADESEAL_QC

ADES_QC

ADESIG

ADESEAL

ADES

- Possible values on indeterminate validation result:

prefix INDETERMINATE is added to the level described in positive result. For example INDETERMINATE_QESIG

- Possible values on negative validation result:

In addition to abovementioned

NOT_ADES_QC_QSCD

NOT_ADES_QC

NOT_ADES

NA

signaturesExt.signatureFormat
String

Format and profile (according to Baseline Profile) of the signature. See XAdES Baseline Profile, CAdES Baseline Profile and PAdES Baseline Profile for detailed description of the Baseline Profile levels.

Possible values:

XAdES_BASELINE_B

XAdES_BASELINE_B_BES

XAdES_BASELINE_B_EPES

XAdES_BASELINE_T

XAdES_BASELINE_LT - long-term level XAdES signature where time-stamp is used as a assertion of trusted signing time

XAdES_BASELINE_LT_TM - long-term level XAdES signature where time-mark is used as a assertion of trusted signing time.

XAdES_BASELINE_LTA

CAdES_BASELINE_B

CAdES_BASELINE_T

CAdES_BASELINE_LT

CAdES_BASELINE_LTA

PAdES_BASELINE_B

PAdES_BASELINE_T

PAdES_BASELINE_LT

PAdES_BASELINE_LTA

signaturesExt.signerSerialNumber
StringSERIALNUMBER value portion in signer's (natural person) certificate's subject distinguished name.
signaturesExt.registrationNumber
StringOID 2.5.4.97 (organizationIdentifier) value portion in signer's (legal person) certificate's subject distinguished name. 
validationTime
DateTime of validating the signature by the service.
signaturesCount
NumberNumber of signatures found inside digitally signed file.
validSignaturesCount
NumberSignatures count that have validated to TOTAL-PASSED. See also SignatureExt.Indication field.
validationLevel
String

Validation process against what the document is validated, only applicable on DSS based validations.

Possible values:

ARCHIVAL_DATA

validatedDocument
ObjectObject containing information about validated document.
validatedDocument. filename
StringDigitally signed document's file name.

Example

{
    "data": {
        "signatureForm": "ASiC-E",
        "signaturesExt": [
            {
                "id": "S1",
                "info": {
                    "bestSignatureTime": "11.11.2019. 08:32:04"
                },
                "signedBy": "ANDRIS PARAUDZIŅŠ",
                "warnings": [
                    {
                        "content": "Signature warnings here"
                    }
                ],
                "indication": "TOTAL-PASSED",
				"subindication": "subindication details here"
                "signatureLevel": "QESIG",
                "signatureFormat": "XAdES_BASELINE_LT",
                "signerSerialNumber": "PNOLV-324954-21338"
            }
        ],
        "validationTime": "30.12.2019. 06:39",
        "signaturesCount": 1,
        "validationLevel": "ARCHIVAL_DATA",
        "validatedDocument": {
            "filename": "test.edoc"
        },
        "validSignaturesCount": 1
    }
}

Koplietošanas API

Koplietošanas uzsākšana

Scope

Add access rights to a specific session.

Description

1. The session is accompanied by information about the person and the level of his/her access rights;

2. If a person who is already attached to the session is subordinate, information is corrected according to the supplied data;

3. The session is set to show that it is shared.

Request

The Service provider's application sends the following GET request using TLS:

POST /api-share/v1.0/{sessionId}/persons

Property

Type

Usage

Description

sessionId
String (64)MandatoryFile processing session identifier

Authorization

The request must contain an Authorization header with an OAuth Introspect access token obtained via Integration Platform a Service provider's credentials grant flow.

Introspect piekļuves talona (token) saņemšana

Description

This operation obtains an OAuth 2.0 access token. This operation can be invoked as part of an OAuth 2.0 Service provider's credentials grant flow.

Introspect access token

When the Service provider's credentials grant flow is used, the obtained access token demonstrates the administrative authorization of the Service provider's application making the call for accessing certain resources or services (i.e., without direct intervention of the resource's owner), or for accessing resources of the Service provider's application. Token is issued when the authorization server that processes the request is not associated to an identity provider. A token of this type can be used for accessing resources not associated to end-users or to end-user resources of any domain.

This type of access token is used to get access to Signature creation and validation service API's

Request

To obtain the token, the Service provider's application must send a request like the following to authorization server using TLS. This request is sent directly from the Service provider’s application to authorization server and does not go via the browser.

POST /trustedx-authserver/oauth/{as}/token

Parameter

Title

Type

Field

Description

as

path

mandatory

Use "lvrtc-eipsign-as"

Host:

Test environment: eidas-demo.eparaksts.lv

Production: eidas.eparaksts.lv

Content-Type Header

Content-Type: application/x-www-form-urlencoded; charset=UTF-8


In HTTP POST request is necessary to incorporated the following main attribute: Authorization – API access token.

Authorization: Basic <API-Key>

How to generate API Access Key

Before Service provider access Integration platform API, LVRTC shall register Service provider as customer of Integration platform. After signing a contract with LVRTC (Test of Production environment) LVRTC generates Service Provider’s application identifier – (client_id) and shared secret (client_secret), intended for the customer usage.
API Access Key (API Key) is generated from the Service provider’s application identifier (client_id), a secret shared with the platform (client_secret)  on the following basis:

Service provider's application identifier client_id are converted using the UTF-8 character encoding and URL encoding conditions.

(warning)  For example, value "Portāls" conversion result is "port%C4%81ls".

Service provider's application password client_secret is converted by using the UTF-8 character encoding and URL encoding conditions.

(warning)  For example, value "drošība" conversion result is "dro%C5%A1%C4%ABba".

Both values of the previous two steps must be combined with separator colon “:” between them.

(warning)  For example, by using previous examples, the result will be "port%C4%81ls:dro%C5%A1%C4%ABba".

Obtained value must be converted using base 64 encoding without line breaks.

(warning)  For example, values "port%C4%81ls:dro%C5%A1%C4%ABba" conversion result is "CG94ydCVDNCUMWxzOmRybyVDNSVBMSVDNCVBQmJh".

"MIME Tools" tool in "Notepad + +" can be used for this purpose.

API-Key = base64[url_encode(utf8(<client_id>)) ':' url_encode(utf8(<client_secret>))]

Body

The content of the request for Introspect access token (used for access SignAPI service):

Property

Usage

Description

grant_type

mandatory

Must have the client_credentials value .

scopemandatoryMust have the urn:safelayer:eidas:oauth:token:introspect value

Example (Introspect access token)

The following example shows a situation in which the Service provider’s application with the identifier "Portal" and the password "drošība" authority shall transmit the request to the server with the identifier "lvrtc-eips-as":

POST /trustedx-authserver/oauth/lvrtc-eipsign-as/token HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Authorization: Basic CG94ydCVDNCUMWxzOmRybyVDNSVBMSVDNCVBQmJh
Host: eidas-demo.eparaksts.lv
grant_type=client_credentials&
			scope=urn%3Asafelayer%3Aeidas%3Aoauth%3Atoken%3Aintrospect

Response

In response, Integration platform authorization server issues a bearer-type OAuth 2.0 access token and returns it in a JSON structure.

{
"access_token" : {string}, 
"token_type" : "Bearer", 
"expires_in" : {number}
}

Parameter

PropertyDescription
access_token
Access token generated by Authorization server. The token has the characteristics specified in the configuration of the authorization server that processed the request and consists of a random string of the number of bytes specified in the Access token number of random bytes (by default, 32), encoded in hexadecimal.
token_type
Type of access token. Always has the "bearer" value. (Bearer type OAuth 2.0 access token).
expires_in
Lifetime (in seconds) of the access token. The Service provider’s application must perform the access the token authorizes before the token expires. This value can be configured in the Token timeout option of the authorization server (by default, 120 seconds). Once this timeout has expired, the token becomes invalid, and the Service provider’s application must obtain another one if it wants to continue invoking the protected services.

Example

Introspect access token:

HTTP/1.1 200 OK
Content-Type: application/json;charset=utf-8 
Cache-Control: no-store, no-cache, must-revalidate 
Pragma: no-cache
{
 "scope": "urn:safelayer:eidas:oauth:token:introspect",
 "access_token": "dfffb0d7f90bed142464750cacad5e4b9e23f58ecb1d77e3bdf706ba208ad16a",
 "token_type": "Bearer",
 "expires_in": 600
}



Content-Type Header

Content-Type: application/json

Body

[ 
 {
    "personId": {String},
    "accessRights": {Integer}
  }
]
PropertyDescription
personId
Identificator of of the person who shall access this session
accessRights
Access rights level. For detailed information, please see "Personas piekļuves saraksta apraksts".

Example

POST /api-share/v1/80832540faff3f90246b71122a4bd6896cd50933cc12a22d99a577b7b41d55e2/Persons HTTP/1.1
Authorization: Bearer a477b3a3366768c07e4c458f518711b4b351e8d2c2f0f78a1524e4d3efd00603
Host: signapi-prep.eparaksts.lv
[
{
    "personId": "111111-11111",
    "accessRights": 5
}
]

Response

JSON object:

{
  "data": {String}
}
PropertyDescription
data
Information about sharing status

Example

{
    "data": "Sharing of the session 80832540faff3f90246b71122a4bd6896cd50933cc12a22d99a577b7b41d55e2 changed. 1 persons added, rights for 0 persons modified"
}

Pārtraukt koplietošanu

Scope

Remove access rights from the specific session.

Description

1. Person access rights to the session is removed

2. If there is no other Persons with whom session is shared, status "shared" is removed from the session.

Request

The Service provider's application sends the following GET request using TLS:

DELETE /api-share/v1.0/{sessionId}/persons/{personId}
PropertyDescription
sessionId
File processing session identifier
personId
Identificator of of the person

Authorization

The request must contain an Authorization header with an OAuth Introspect access token obtained via Integration Platform a Service provider's credentials grant flow.

Introspect piekļuves talona (token) saņemšana

Description

This operation obtains an OAuth 2.0 access token. This operation can be invoked as part of an OAuth 2.0 Service provider's credentials grant flow.

Introspect access token

When the Service provider's credentials grant flow is used, the obtained access token demonstrates the administrative authorization of the Service provider's application making the call for accessing certain resources or services (i.e., without direct intervention of the resource's owner), or for accessing resources of the Service provider's application. Token is issued when the authorization server that processes the request is not associated to an identity provider. A token of this type can be used for accessing resources not associated to end-users or to end-user resources of any domain.

This type of access token is used to get access to Signature creation and validation service API's

Request

To obtain the token, the Service provider's application must send a request like the following to authorization server using TLS. This request is sent directly from the Service provider’s application to authorization server and does not go via the browser.

POST /trustedx-authserver/oauth/{as}/token

Parameter

Title

Type

Field

Description

as

path

mandatory

Use "lvrtc-eipsign-as"

Host:

Test environment: eidas-demo.eparaksts.lv

Production: eidas.eparaksts.lv

Content-Type Header

Content-Type: application/x-www-form-urlencoded; charset=UTF-8


In HTTP POST request is necessary to incorporated the following main attribute: Authorization – API access token.

Authorization: Basic <API-Key>

How to generate API Access Key

Before Service provider access Integration platform API, LVRTC shall register Service provider as customer of Integration platform. After signing a contract with LVRTC (Test of Production environment) LVRTC generates Service Provider’s application identifier – (client_id) and shared secret (client_secret), intended for the customer usage.
API Access Key (API Key) is generated from the Service provider’s application identifier (client_id), a secret shared with the platform (client_secret)  on the following basis:

Service provider's application identifier client_id are converted using the UTF-8 character encoding and URL encoding conditions.

(warning)  For example, value "Portāls" conversion result is "port%C4%81ls".

Service provider's application password client_secret is converted by using the UTF-8 character encoding and URL encoding conditions.

(warning)  For example, value "drošība" conversion result is "dro%C5%A1%C4%ABba".

Both values of the previous two steps must be combined with separator colon “:” between them.

(warning)  For example, by using previous examples, the result will be "port%C4%81ls:dro%C5%A1%C4%ABba".

Obtained value must be converted using base 64 encoding without line breaks.

(warning)  For example, values "port%C4%81ls:dro%C5%A1%C4%ABba" conversion result is "CG94ydCVDNCUMWxzOmRybyVDNSVBMSVDNCVBQmJh".

"MIME Tools" tool in "Notepad + +" can be used for this purpose.

API-Key = base64[url_encode(utf8(<client_id>)) ':' url_encode(utf8(<client_secret>))]

Body

The content of the request for Introspect access token (used for access SignAPI service):

Property

Usage

Description

grant_type

mandatory

Must have the client_credentials value .

scopemandatoryMust have the urn:safelayer:eidas:oauth:token:introspect value

Example (Introspect access token)

The following example shows a situation in which the Service provider’s application with the identifier "Portal" and the password "drošība" authority shall transmit the request to the server with the identifier "lvrtc-eips-as":

POST /trustedx-authserver/oauth/lvrtc-eipsign-as/token HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Authorization: Basic CG94ydCVDNCUMWxzOmRybyVDNSVBMSVDNCVBQmJh
Host: eidas-demo.eparaksts.lv
grant_type=client_credentials&
			scope=urn%3Asafelayer%3Aeidas%3Aoauth%3Atoken%3Aintrospect

Response

In response, Integration platform authorization server issues a bearer-type OAuth 2.0 access token and returns it in a JSON structure.

{
"access_token" : {string}, 
"token_type" : "Bearer", 
"expires_in" : {number}
}

Parameter

PropertyDescription
access_token
Access token generated by Authorization server. The token has the characteristics specified in the configuration of the authorization server that processed the request and consists of a random string of the number of bytes specified in the Access token number of random bytes (by default, 32), encoded in hexadecimal.
token_type
Type of access token. Always has the "bearer" value. (Bearer type OAuth 2.0 access token).
expires_in
Lifetime (in seconds) of the access token. The Service provider’s application must perform the access the token authorizes before the token expires. This value can be configured in the Token timeout option of the authorization server (by default, 120 seconds). Once this timeout has expired, the token becomes invalid, and the Service provider’s application must obtain another one if it wants to continue invoking the protected services.

Example

Introspect access token:

HTTP/1.1 200 OK
Content-Type: application/json;charset=utf-8 
Cache-Control: no-store, no-cache, must-revalidate 
Pragma: no-cache
{
 "scope": "urn:safelayer:eidas:oauth:token:introspect",
 "access_token": "dfffb0d7f90bed142464750cacad5e4b9e23f58ecb1d77e3bdf706ba208ad16a",
 "token_type": "Bearer",
 "expires_in": 600
}



Example

DELETE /api-share/v1/80832540faff3f90246b71122a4bd6896cd50933cc12a22d99a577b7b41d55e2/Persons/111111-11111 HTTP/1.1
Authorization: Bearer a477b3a3366768c07e4c458f518711b4b351e8d2c2f0f78a1524e4d3efd00603
Host: signapi-prep.eparaksts.lv

Response

JSON object:

{
  "data": {String}
}
PropertyDescription
data
Information about operation status

Example

{
    "data": "Sharing of the session 552825f4eafdbf90a676ea40c4802c9d1f27c20373c2594c0dfe950976ce2b19 removed for 1 person"
}

Persons in session

Scope

Find out the persons with whom session is shared.

Description

Returns a list of people associated with the session.

Request

The Service provider's application sends the following GET request using TLS:

GET /api-share/v1.0/{sessionId}/persons

Property

Type

Usage

Description

sessionId
String (64)MandatoryFile processing session identifier

Authorization

The request must contain an Authorization header with an OAuth Introspect access token obtained via Integration Platform a Service provider's credentials grant flow.

Introspect piekļuves talona (token) saņemšana

Description

This operation obtains an OAuth 2.0 access token. This operation can be invoked as part of an OAuth 2.0 Service provider's credentials grant flow.

Introspect access token

When the Service provider's credentials grant flow is used, the obtained access token demonstrates the administrative authorization of the Service provider's application making the call for accessing certain resources or services (i.e., without direct intervention of the resource's owner), or for accessing resources of the Service provider's application. Token is issued when the authorization server that processes the request is not associated to an identity provider. A token of this type can be used for accessing resources not associated to end-users or to end-user resources of any domain.

This type of access token is used to get access to Signature creation and validation service API's

Request

To obtain the token, the Service provider's application must send a request like the following to authorization server using TLS. This request is sent directly from the Service provider’s application to authorization server and does not go via the browser.

POST /trustedx-authserver/oauth/{as}/token

Parameter

Title

Type

Field

Description

as

path

mandatory

Use "lvrtc-eipsign-as"

Host:

Test environment: eidas-demo.eparaksts.lv

Production: eidas.eparaksts.lv

Content-Type Header

Content-Type: application/x-www-form-urlencoded; charset=UTF-8


In HTTP POST request is necessary to incorporated the following main attribute: Authorization – API access token.

Authorization: Basic <API-Key>

How to generate API Access Key

Before Service provider access Integration platform API, LVRTC shall register Service provider as customer of Integration platform. After signing a contract with LVRTC (Test of Production environment) LVRTC generates Service Provider’s application identifier – (client_id) and shared secret (client_secret), intended for the customer usage.
API Access Key (API Key) is generated from the Service provider’s application identifier (client_id), a secret shared with the platform (client_secret)  on the following basis:

Service provider's application identifier client_id are converted using the UTF-8 character encoding and URL encoding conditions.

(warning)  For example, value "Portāls" conversion result is "port%C4%81ls".

Service provider's application password client_secret is converted by using the UTF-8 character encoding and URL encoding conditions.

(warning)  For example, value "drošība" conversion result is "dro%C5%A1%C4%ABba".

Both values of the previous two steps must be combined with separator colon “:” between them.

(warning)  For example, by using previous examples, the result will be "port%C4%81ls:dro%C5%A1%C4%ABba".

Obtained value must be converted using base 64 encoding without line breaks.

(warning)  For example, values "port%C4%81ls:dro%C5%A1%C4%ABba" conversion result is "CG94ydCVDNCUMWxzOmRybyVDNSVBMSVDNCVBQmJh".

"MIME Tools" tool in "Notepad + +" can be used for this purpose.

API-Key = base64[url_encode(utf8(<client_id>)) ':' url_encode(utf8(<client_secret>))]

Body

The content of the request for Introspect access token (used for access SignAPI service):

Property

Usage

Description

grant_type

mandatory

Must have the client_credentials value .

scopemandatoryMust have the urn:safelayer:eidas:oauth:token:introspect value

Example (Introspect access token)

The following example shows a situation in which the Service provider’s application with the identifier "Portal" and the password "drošība" authority shall transmit the request to the server with the identifier "lvrtc-eips-as":

POST /trustedx-authserver/oauth/lvrtc-eipsign-as/token HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Authorization: Basic CG94ydCVDNCUMWxzOmRybyVDNSVBMSVDNCVBQmJh
Host: eidas-demo.eparaksts.lv
grant_type=client_credentials&
			scope=urn%3Asafelayer%3Aeidas%3Aoauth%3Atoken%3Aintrospect

Response

In response, Integration platform authorization server issues a bearer-type OAuth 2.0 access token and returns it in a JSON structure.

{
"access_token" : {string}, 
"token_type" : "Bearer", 
"expires_in" : {number}
}

Parameter

PropertyDescription
access_token
Access token generated by Authorization server. The token has the characteristics specified in the configuration of the authorization server that processed the request and consists of a random string of the number of bytes specified in the Access token number of random bytes (by default, 32), encoded in hexadecimal.
token_type
Type of access token. Always has the "bearer" value. (Bearer type OAuth 2.0 access token).
expires_in
Lifetime (in seconds) of the access token. The Service provider’s application must perform the access the token authorizes before the token expires. This value can be configured in the Token timeout option of the authorization server (by default, 120 seconds). Once this timeout has expired, the token becomes invalid, and the Service provider’s application must obtain another one if it wants to continue invoking the protected services.

Example

Introspect access token:

HTTP/1.1 200 OK
Content-Type: application/json;charset=utf-8 
Cache-Control: no-store, no-cache, must-revalidate 
Pragma: no-cache
{
 "scope": "urn:safelayer:eidas:oauth:token:introspect",
 "access_token": "dfffb0d7f90bed142464750cacad5e4b9e23f58ecb1d77e3bdf706ba208ad16a",
 "token_type": "Bearer",
 "expires_in": 600
}



Example

GET /api-share/v1/552825f4eafdbf90a676ea40c4802c9d1f27c20373c2594c0dfe950976ce2b19/Persons HTTP/1.1
Authorization: Bearer a477b3a3366768c07e4c458f518711b4b351e8d2c2f0f78a1524e4d3efd00603
Host: signapi-prep.eparaksts.lv

Response

JSON object:

{
  "data": [
    {
      "personId": {String},
      "accessRights": {Integer}
    }
  ]
}
PropertyDescription
personId
Identificator of of the person who shall access this session
accessRights
Access rights level. For detailed information, please see "Person access list description".

Example

{
    "data": [
        {
            "personId": "111111-11111",
            "accessRights": 5
        },
        {
            "personId": "222222-22222",
            "accessRights": 1
        }
    ]
}

Personas sesijas

Scope

Find out the sessions which are shared with the specific person .

Description

Returns a list of the sessions associated to the person.

Request

The Service provider's application sends the following GET request using TLS:

GET /api-share/v1.0/{personId}/sessions
PropertyDescription
personId
Identificator of the person

Authorization

The request must contain an Authorization header with an OAuth Introspect access token obtained via Integration Platform a Service provider's credentials grant flow.

Introspect piekļuves talona (token) saņemšana

Description

This operation obtains an OAuth 2.0 access token. This operation can be invoked as part of an OAuth 2.0 Service provider's credentials grant flow.

Introspect access token

When the Service provider's credentials grant flow is used, the obtained access token demonstrates the administrative authorization of the Service provider's application making the call for accessing certain resources or services (i.e., without direct intervention of the resource's owner), or for accessing resources of the Service provider's application. Token is issued when the authorization server that processes the request is not associated to an identity provider. A token of this type can be used for accessing resources not associated to end-users or to end-user resources of any domain.

This type of access token is used to get access to Signature creation and validation service API's

Request

To obtain the token, the Service provider's application must send a request like the following to authorization server using TLS. This request is sent directly from the Service provider’s application to authorization server and does not go via the browser.

POST /trustedx-authserver/oauth/{as}/token

Parameter

Title

Type

Field

Description

as

path

mandatory

Use "lvrtc-eipsign-as"

Host:

Test environment: eidas-demo.eparaksts.lv

Production: eidas.eparaksts.lv

Content-Type Header

Content-Type: application/x-www-form-urlencoded; charset=UTF-8


In HTTP POST request is necessary to incorporated the following main attribute: Authorization – API access token.

Authorization: Basic <API-Key>

How to generate API Access Key

Before Service provider access Integration platform API, LVRTC shall register Service provider as customer of Integration platform. After signing a contract with LVRTC (Test of Production environment) LVRTC generates Service Provider’s application identifier – (client_id) and shared secret (client_secret), intended for the customer usage.
API Access Key (API Key) is generated from the Service provider’s application identifier (client_id), a secret shared with the platform (client_secret)  on the following basis:

Service provider's application identifier client_id are converted using the UTF-8 character encoding and URL encoding conditions.

(warning)  For example, value "Portāls" conversion result is "port%C4%81ls".

Service provider's application password client_secret is converted by using the UTF-8 character encoding and URL encoding conditions.

(warning)  For example, value "drošība" conversion result is "dro%C5%A1%C4%ABba".

Both values of the previous two steps must be combined with separator colon “:” between them.

(warning)  For example, by using previous examples, the result will be "port%C4%81ls:dro%C5%A1%C4%ABba".

Obtained value must be converted using base 64 encoding without line breaks.

(warning)  For example, values "port%C4%81ls:dro%C5%A1%C4%ABba" conversion result is "CG94ydCVDNCUMWxzOmRybyVDNSVBMSVDNCVBQmJh".

"MIME Tools" tool in "Notepad + +" can be used for this purpose.

API-Key = base64[url_encode(utf8(<client_id>)) ':' url_encode(utf8(<client_secret>))]

Body

The content of the request for Introspect access token (used for access SignAPI service):

Property

Usage

Description

grant_type

mandatory

Must have the client_credentials value .

scopemandatoryMust have the urn:safelayer:eidas:oauth:token:introspect value

Example (Introspect access token)

The following example shows a situation in which the Service provider’s application with the identifier "Portal" and the password "drošība" authority shall transmit the request to the server with the identifier "lvrtc-eips-as":

POST /trustedx-authserver/oauth/lvrtc-eipsign-as/token HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Authorization: Basic CG94ydCVDNCUMWxzOmRybyVDNSVBMSVDNCVBQmJh
Host: eidas-demo.eparaksts.lv
grant_type=client_credentials&
			scope=urn%3Asafelayer%3Aeidas%3Aoauth%3Atoken%3Aintrospect

Response

In response, Integration platform authorization server issues a bearer-type OAuth 2.0 access token and returns it in a JSON structure.

{
"access_token" : {string}, 
"token_type" : "Bearer", 
"expires_in" : {number}
}

Parameter

PropertyDescription
access_token
Access token generated by Authorization server. The token has the characteristics specified in the configuration of the authorization server that processed the request and consists of a random string of the number of bytes specified in the Access token number of random bytes (by default, 32), encoded in hexadecimal.
token_type
Type of access token. Always has the "bearer" value. (Bearer type OAuth 2.0 access token).
expires_in
Lifetime (in seconds) of the access token. The Service provider’s application must perform the access the token authorizes before the token expires. This value can be configured in the Token timeout option of the authorization server (by default, 120 seconds). Once this timeout has expired, the token becomes invalid, and the Service provider’s application must obtain another one if it wants to continue invoking the protected services.

Example

Introspect access token:

HTTP/1.1 200 OK
Content-Type: application/json;charset=utf-8 
Cache-Control: no-store, no-cache, must-revalidate 
Pragma: no-cache
{
 "scope": "urn:safelayer:eidas:oauth:token:introspect",
 "access_token": "dfffb0d7f90bed142464750cacad5e4b9e23f58ecb1d77e3bdf706ba208ad16a",
 "token_type": "Bearer",
 "expires_in": 600
}



Example

GET /api-share/v1/111111-111111/Sessions HTTP/1.1
Authorization: Bearer a477b3a3366768c07e4c458f518711b4b351e8d2c2f0f78a1524e4d3efd00603
Host: signapi-prep.eparaksts.lv

Response

JSON object:

{
  "data": [
    {
      "sessionId": {String},
      "fileCount": {Integer},
      "personCount": {Integer},
      "signed": {Integer},
      "shared": {Boolean},
      "archived": {Boolean},
      "signedFileType": {String},
      "lastModified": {String},
      "removalTime":{String}
    }
  ]
}
PropertyDescription
sessionId
File processing session identifier
fileCount
File amount in the session
personCount
Number of people the session was shared with
signed

Session signing status:

0 - files loaded but not signed

1 - already signed files where loaded

2 - files signed

shared

Sharing statuss:

false - session is not shared

true - session is shared

archived

Archive timestamp statuss:

false - do not contain archive timestap

true - archive timestap added

signedFileType
If signed, shows format of the signed file
lastModified
Time of last file processing request
removalTime
Expected process deletion time

Example

{
    "data": [
        {
            "sessionId": "552825f4eafdbf90a676ea40c4802c9d1f27c20373c2594c0dfe950976ce2b19",
            "fileCount": 0,
            "personCount": 2,
            "signed": 0,
            "shared": false,
            "archived": false,
            "lastModified": "0001-01-01T00:00:00",
            "removalTime": "0001-01-01T00:00:00"
        },
        {
            "sessionId": "1d72da6fd2d71810f96d04e9261bee6f3b01eaba95ed9b25be0cd6230910902b",
            "fileCount": 0,
            "personCount": 1,
            "signed": 0,
            "shared": false,
            "archived": false,
            "lastModified": "0001-01-01T00:00:00",
            "removalTime": "0001-01-01T00:00:00"
        }
    ]
}

Person access list description

PropertyDecsription
accessRights

Access rights values:

1 - Sign

2 - Delete

4 - Read

8 - Share

16 - Reserved

(warning)"accessRights" value is a summ of all neded operations. Value is from "0" (no access rights) to "31" (Sign+Delete+Read+Share+Reserved).(warning)



Konfigurācijas API

Savas reģistrētās konfigurācijas saņemšana

Scope

Returns Service Provider configuration registered in the Sign API service. 

Description

Configuration information about the authorized Service provider is returned.

Request

The Service provider's application sends the following GET request using TLS:

GET /api-config/v1.0/

Authorization

The request must contain an Authorization header with an OAuth Introspect access token obtained via Integration Platform a Service provider's credentials grant flow.

Introspect piekļuves talona (token) saņemšana

Description

This operation obtains an OAuth 2.0 access token. This operation can be invoked as part of an OAuth 2.0 Service provider's credentials grant flow.

Introspect access token

When the Service provider's credentials grant flow is used, the obtained access token demonstrates the administrative authorization of the Service provider's application making the call for accessing certain resources or services (i.e., without direct intervention of the resource's owner), or for accessing resources of the Service provider's application. Token is issued when the authorization server that processes the request is not associated to an identity provider. A token of this type can be used for accessing resources not associated to end-users or to end-user resources of any domain.

This type of access token is used to get access to Signature creation and validation service API's

Request

To obtain the token, the Service provider's application must send a request like the following to authorization server using TLS. This request is sent directly from the Service provider’s application to authorization server and does not go via the browser.

POST /trustedx-authserver/oauth/{as}/token

Parameter

Title

Type

Field

Description

as

path

mandatory

Use "lvrtc-eipsign-as"

Host:

Test environment: eidas-demo.eparaksts.lv

Production: eidas.eparaksts.lv

Content-Type Header

Content-Type: application/x-www-form-urlencoded; charset=UTF-8


In HTTP POST request is necessary to incorporated the following main attribute: Authorization – API access token.

Authorization: Basic <API-Key>

How to generate API Access Key

Before Service provider access Integration platform API, LVRTC shall register Service provider as customer of Integration platform. After signing a contract with LVRTC (Test of Production environment) LVRTC generates Service Provider’s application identifier – (client_id) and shared secret (client_secret), intended for the customer usage.
API Access Key (API Key) is generated from the Service provider’s application identifier (client_id), a secret shared with the platform (client_secret)  on the following basis:

Service provider's application identifier client_id are converted using the UTF-8 character encoding and URL encoding conditions.

(warning)  For example, value "Portāls" conversion result is "port%C4%81ls".

Service provider's application password client_secret is converted by using the UTF-8 character encoding and URL encoding conditions.

(warning)  For example, value "drošība" conversion result is "dro%C5%A1%C4%ABba".

Both values of the previous two steps must be combined with separator colon “:” between them.

(warning)  For example, by using previous examples, the result will be "port%C4%81ls:dro%C5%A1%C4%ABba".

Obtained value must be converted using base 64 encoding without line breaks.

(warning)  For example, values "port%C4%81ls:dro%C5%A1%C4%ABba" conversion result is "CG94ydCVDNCUMWxzOmRybyVDNSVBMSVDNCVBQmJh".

"MIME Tools" tool in "Notepad + +" can be used for this purpose.

API-Key = base64[url_encode(utf8(<client_id>)) ':' url_encode(utf8(<client_secret>))]

Body

The content of the request for Introspect access token (used for access SignAPI service):

Property

Usage

Description

grant_type

mandatory

Must have the client_credentials value .

scopemandatoryMust have the urn:safelayer:eidas:oauth:token:introspect value

Example (Introspect access token)

The following example shows a situation in which the Service provider’s application with the identifier "Portal" and the password "drošība" authority shall transmit the request to the server with the identifier "lvrtc-eips-as":

POST /trustedx-authserver/oauth/lvrtc-eipsign-as/token HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Authorization: Basic CG94ydCVDNCUMWxzOmRybyVDNSVBMSVDNCVBQmJh
Host: eidas-demo.eparaksts.lv
grant_type=client_credentials&
			scope=urn%3Asafelayer%3Aeidas%3Aoauth%3Atoken%3Aintrospect

Response

In response, Integration platform authorization server issues a bearer-type OAuth 2.0 access token and returns it in a JSON structure.

{
"access_token" : {string}, 
"token_type" : "Bearer", 
"expires_in" : {number}
}

Parameter

PropertyDescription
access_token
Access token generated by Authorization server. The token has the characteristics specified in the configuration of the authorization server that processed the request and consists of a random string of the number of bytes specified in the Access token number of random bytes (by default, 32), encoded in hexadecimal.
token_type
Type of access token. Always has the "bearer" value. (Bearer type OAuth 2.0 access token).
expires_in
Lifetime (in seconds) of the access token. The Service provider’s application must perform the access the token authorizes before the token expires. This value can be configured in the Token timeout option of the authorization server (by default, 120 seconds). Once this timeout has expired, the token becomes invalid, and the Service provider’s application must obtain another one if it wants to continue invoking the protected services.

Example

Introspect access token:

HTTP/1.1 200 OK
Content-Type: application/json;charset=utf-8 
Cache-Control: no-store, no-cache, must-revalidate 
Pragma: no-cache
{
 "scope": "urn:safelayer:eidas:oauth:token:introspect",
 "access_token": "dfffb0d7f90bed142464750cacad5e4b9e23f58ecb1d77e3bdf706ba208ad16a",
 "token_type": "Bearer",
 "expires_in": 600
}



Example

GET /api-config/v1.0/ HTTP/1.1
Authorization: Bearer a477b3a3366768c07e4c458f518711b4b351e8d2c2f0f78a1524e4d3efd00603
Host: signapi-prep.eparaksts.lv

Response

JSON object:

"data": {
    "oauthClientId": {String},
    "name": {String},
    "created": {Datetime},
    "changed": {Datetime},
    "fileMaxLength": {Number},
    "sessionExpirationTimeout": {Number}
}


PropertyDescription
data
Contains information about Service providers configuration
data.oauthClientId
OAuth2.0 Service provider’s application identifier issued by LVRTC
data.name
Registered name of Service provider
data.created
Date of creation
data.changed
Date of last modifications
data.fileMaxLength
Maximal possible upload file size
data.sessionExpirationTimeout
Session expiration in seconds

Example

"data": {
    "oauthClientId": "SIAUznemums",
    "name": "SIA Uzņēmums",
    "created": "2019-10-22T10:34:10.666528",
    "changed": "2019-10-22T10:34:10.666528",
    "fileMaxLength": 4202406,
    "sessionExpirationTimeout": 5105880
}

Dokumentu parakstīšanas piemērs

Sign API izsaukumu piemēri Postman kolekciju veidā


Rest API pieprasījumu Postman kolekcijas* iespējams lejupielādēt šeit.

Pamācībā kā importēt kolekcijas un vidi pieejama šeit.


*Obligāti jāimportē gan .postman_collection, gan .postman_environment fails. Kā arī jāizmaina "PUBLIC SignAPI PREP" vides mainīgie uz klientam piešķirtajiem "client_id", "client_password" un "redirect_uri".

  • No labels