Signature in Organisation ID Service

Initiate sign method

This method is used by a Relying Party to initiate a signing transaction. The method is intended for creating signatures both in online contexts, where the access to the Relying Party's service or application is initiated by the end user, as well as in offline contexts, where the signature request is initiated by the Relying Party's service in its own right. Signature transactions, therefore, have configurable longevity — from the point of initiation, the user has between two minutes and 30 days to confirm the signature request. As opposed to authentication requests, multiple signature requests may be active at any given time, from the same or different relying parties.

Although in most cases possession and control of the handheld device on which a Freja eID app is installed are sufficient for allowing the user to view transaction content when initiating a transaction, a Relying Party can also specify whether the content is confidential or not. The confidentiality flag governs whether the user must present the PIN or, if enabled, use one of the biometric authentication alternatives on the handheld device, before being allowed to view the transaction content. The option effectively provides an option to have transactions that are "signed-for (for viewing) with explicit consent (for accepting the content)".

The method is called using HTTP POST through the URLs below:

System
Method endpoints
Test
https://services.test.frejaeid.com/organisation/sign/1.0/init
Production
https://services.prod.frejaeid.com/organisation/sign/1.0/init

You need to have an Organisation ID set for a user to be able to initiate signature requests using these URLs. If that is not the case, please refer to Organisation ID Service


The parameter of the method is a Base64 UTF8-encoded JSON payload according to the following:

Parameter name
Value
initSignRequest
{
   "userInfoType":"User info type",
   "userInfo":"User information corresponding to user info type",
   "title":"Title to display in transaction list",
   "pushNotification":{
      "title":"Title to display in push notification to user",
      "text":"Text to display in push notification to user"
   },
   "expiry":"Expiry time for the request",
   "dataToSignType":"Type of data to sign",
   "dataToSign":"The data to be signed",
   "signatureType":"Signature type",
   "attributesToReturn":[
      {
         "attribute":"Type of attribute to be returned"
      }
   ],
   "orgIdIssuer":"Optional, should be ANY if requested organisation ID is set by another Relying Party"
}

userInfoType: string, mandatory. Describes the type of user information supplied to identify the end user. Currently one of:

  • ORG_ID (specific organisation identifier),
  • PHONE (end user's telephone number),
  • EMAIL (end user's email),
  • SSN (end user's social security number),
  • INFERRED (for QR code sign transactions).

userInfo: string, mandatory, 256 characters maximum. If userInfoType is EMAIL or PHONE, interpreted as a string value of the email or telephone number of the end user, respectively. If userInfoType is INFERRED, then userInfo must be set to: "N/A" because there is no data for the user to enter. If userInfoType is SSN, then it must be a Base64 encoding of the ssnuserinfo JSON structure described below.

If userInfoType is PHONE, the userInfo value MUST be in the form of: "+4673*******"; the leading plus '+' is present whereas the leading zero from the mobile phone operator code '0' is not. (See example below)

The combination of userInfoType INFERRED and userInfo N/A is used when the user is signing data by scanning a QR code. For more details please see Implementation - Troubleshooting and Best Practices.

Inferred transactions are not bound to a specific user upon initiation, they are bound to a user when a QR code is scanned. That is, the first user that scans the QR code of a pending inferred transaction gets bound to it.

As such you need to be aware of the privacy of the content contained in signature request: if the content is sensitive and intended for a specific recipient we strongly advise you to use one of the binding forms of the signature API.

ssnuserinfo
{
   "country":"Country of SSN",
   "ssn":"Social security number of the end user"
}

country: string, mandatory. Contains the ISO-3166 two-alphanumeric country code of the country where the SSN is issued. In the current version of Freja eID, one of: ''SE'' (Sweden), ''NO'' (Norway), ''FI'' (Finland), ''DK'' (Danmark).
ssn: string, mandatory. Expected SSN of the end user as per pre-registration.

  • If country equal to "SE", the value must be the 12-digit format of the Swedish "personnummer" without spaces or hyphens. Example: 195210131234.
  • If country equal to ''NO'', the value must be the 11-digit format of the Norwegian "personnummer" without spaces or hyphens. Example: 13105212345.
  • If country equal to ''FI'', the value must be the 10-characters format of the Finish ''koodi'', with the hyphen before the last four control characters. Hyphen can be replaced with the letter A. Example format: 131052-308T or 131052A308T.
  • If country equal to ''DK'', the value must be the 10-digit format of the Danish "personnummer" without spaces or hyphens. Example: 1310521234.

title: String, optional, 128 characters maximum. The title to display in the transaction list if presented to the user on the mobile device. The title will be presented regardless of the confidentiality setting (see below). If not present, a system default text will be presented.

pushNotification: JSON structure, optional. The title and the text of the notification sent to the mobile device to alert the user of a signature request. The character limit for the push notification title and text is 256 characters for each. If not present, a system default title and text will be presented.

How much text the user sees in the push notification depends on the device's screen size.

expiry: Long, optional. Describes the time until which the Relying Party is ready to wait for the user to confirm the signature request. Expressed in milliseconds since January 1, 1970, 00:00 UTC. Minimum value is current time +2 minutes, maximum value is current time +30 days. If not present, defaults to current time +2 minutes.

Maximum expiry time for transactions with userInfo set to INFERRED is current time +30 minutes. If not present, defaults to current time +2 minutes.

dataToSignType: String, mandatory. Describes the type of data to be signed. Currently, SIMPLE_UTF8_TEXT and EXTENDED_UTF8_TEXT are supported.

dataToSign: JSON structure, mandatory. Subject to dataToSignType; If SIMPLE_UTF8_TEXT, then all of dataToSign will be displayed to the user prior to soliciting signature approval. If EXTENDED_UTF8_TEXT, then one part will be displayed to the user prior to soliciting signature approval, while the binaryData part of dataToSign will not. JSON structure described below.

dataToSignTypeSIMPLE_UTF8_TEXT
dataToSign
{
   "text":"Base64 encoded UTF-8 text displayed to the end user"
}

text: String, mandatory, 4096 plain text characters maximum prior to Base64 encoding. The text that will be shown in the mobile application and signed by the end user. The content of the Base64 string are bytes representing a UTF-8 encoding of the text to be displayed to and signed by the user.

dataToSignTypeEXTENDED_UTF8_TEXT
dataToSign
{
	"text":"Base64 encoded UTF-8 text displayed to the end user",
	"binaryData":"Base64 encoded byte array not displayed to the user"
}

text: String, mandatory, 4096 plain text characters maximum prior to Base64 encoding. The text that will be shown in the mobile application and signed by the end user. The content of the Base64 string are bytes representing a UTF-8 encoding of the text to be displayed to and signed by the user.

binaryData: String, mandatory, 5 MB maximum prior to Base64 encoding. This is not shown to the user in the mobile application but is, nonetheless included in the signature.

signatureType: string, mandatory. The type of signature that is requested. Currently, SIMPLE and EXTENDED are supported and must match the dataToSignType parameter.

Signature types

Simple signature type

The Simple signature type allows signing of UTF-8 text. Upon completion of the signature by the user, the Relying Party receives a JWS structure containing the data that was presented to the user, as well as evidence that the Freja eID infrastructure has validated the signature.

Extended signature type

The extended signature type allows signing of UTF-8 text (presented to the user) alongside binary data (not presented to the user). Upon completion of the signature by the user, the Relying Party receives a JWS structure containing the data that was presented to the user and the supplied binary data, as well as evidence that the Freja eID infrastructure has validated the signature.

attributesToReturn: list of objects, optional. When retrieving results, additional information about the user can be returned based on the type of attributes required through this parameter. Each object should contain one attribute. Currently supported attribute types are:

  • BASIC_USER_INFO (name and surname), 
  • EMAIL_ADDRESS (user's primary email address),

    If you would prefer an email with a specific email domain please get in touch with partnersupport@frejaeid.com.

  • ALL_EMAIL_ADDRESSES (all user's email addresses),
  • ALL_PHONE_NUMBERS (all user's phone numbers),
  • DATE_OF_BIRTH (date of birth),

  • AGE (user's age based on their date of birth),
  • PHOTO (user's photo, Base64 encoded PNG bytes),
  • ADDRESSES (user's current addresses),
  • SSN (social security number and country),
  • DOCUMENT (information about the document used for registration),
  • REGISTRATION_LEVEL (the user's registration level in Freja eID),
  • ORGANISATION_ID_IDENTIFIER (specific organisation identifier set for the end user by the Relying Party through the Organisation ID Service), 
  • ORGANISATION_ID (specific organisation identifier set for the end user by the Relying Party, relying party localised (EN and SV) friendly name, relying party organisation code and additional attributes),
  • RELYING_PARTY_USER_ID (a unique, user-specific value that allows the Relying Party to identify the same user across multiple sessions),
  • INTEGRATOR_SPECIFIC_USER_ID (a unique, user-specific value that allows the Integrator to identify the same user across multiple sessions regardless of the Integrated Relying Party service that the user is using. For more info, see Integrator Relying Party Management),
  • CUSTOM_IDENTIFIER (a unique, Relying Party-specific, user identifier, set by the Relying Party through the Custom Identifier Management)

orgIdIssuer: ORGANISATION_ID_IDENTIFIER  or ORGANISATION_ID can be requested even if it is set by another Relying Party. Do this by setting the orgIdIssuer parameter to ANY.

In order to be able to request organisation ID set by another Relying Party, you must first get in touch with partnersupport@frejaeid.com.

Example request with userInfoType set to ORG_ID:

If you wish to initiate a signature request for a user with the specific organisation identifier 'vejobla', follow these steps:

  1. Create the JSON structure {"userInfoType":"ORG_ID","userInfo":"vejobla","title":"Sign transaction","expiry":1517526000000,"dataToSignType":"SIMPLE_UTF8_TEXT",
    "dataToSign":{"text":"VGhpcyBpcyBhIHRleHQgZm9yIHNpZ24gdHJhbnNhY3Rpb24u"},"signatureType":"SIMPLE","attributesToReturn":[{"attribute":"BASIC_USER_INFO"}]}
  2. Encode the JSON structure to Base64.
  3. Create the HTTP POST request with a POST parameter name initSignRequest and the Base64 encoded JSON structure from the step 2 as its value.

The HTTP body should be the following (compact format, line broken for clarity only):

initSignRequest=eyJ1c2VySW5mb1R5cGUiOiJPUkdfSUQiLCJ1c2VySW5mbyI6InZlam9ibGEiLC
J0aXRsZSI6IlNpZ24gdHJhbnNhY3Rpb24iLCJleHBpcnkiOjE1MTc1MjYwMDAwMDAsImRhdGFUb1Np
Z25UeXBlIjoiU0lNUExFX1VURjhfVEVYVCIsImRhdGFUb1NpZ24iOnsidGV4dCI6IlZHaHBjeUJwY3
lCaElIUmxlSFFnWm05eUlITnBaMjRnZEhKaGJuTmhZM1JwYjI0dSJ9LCJzaWduYXR1cmVUeXBlIjoi
U0lNUExFIiwiYXR0cmlidXRlc1RvUmV0dXJuIjpbeyJhdHRyaWJ1dGUiOiJCQVNJQ19VU0VSX0lORk
8ifV19
Example request with userInfoType set to EMAIL:

If you wish to initiate a signature request for a user with an email address joe.black@verisec.com, follow these steps:

  1. Create the JSON structure {"userInfoType":"EMAIL","userInfo":"joe.black@verisec.com","title":"Sign transaction","expiry":1517526000000,"dataToSignType":"SIMPLE_UTF8_TEXT",
    "dataToSign":{"text":"VGhpcyBpcyBhIHRleHQgZm9yIHNpZ24gdHJhbnNhY3Rpb24u"},"signatureType":"SIMPLE","attributesToReturn":[{"attribute":"ORGANISATION_ID_IDENTIFIER"}]}
  2. Encode the JSON structure to Base64.
  3. Create the HTTP POST request with a POST parameter name initSignRequest and the Base64 encoded JSON structure from the step 2 as its value.

The HTTP body should be the following (compact format, line broken for clarity only):

initSignRequest=eyJ1c2VySW5mb1R5cGUiOiJFTUFJTCIsInVzZXJJbmZvIjoiam9lLmJsYWNrQH
ZlcmlzZWMuY29tIiwidGl0bGUiOiJTaWduIHRyYW5zYWN0aW9uIiwiZXhwaXJ5IjoxNTE3NTI2MDAw
MDAwLCJkYXRhVG9TaWduVHlwZSI6IlNJTVBMRV9VVEY4X1RFWFQiLAoiZGF0YVRvU2lnbiI6eyJ0ZX
h0IjoiVkdocGN5QnBjeUJoSUhSbGVIUWdabTl5SUhOcFoyNGdkSEpoYm5OaFkzUnBiMjR1In0sInNp
Z25hdHVyZVR5cGUiOiJTSU1QTEUiLCJhdHRyaWJ1dGVzVG9SZXR1cm4iOlt7ImF0dHJpYnV0ZSI6Ik
9SR0FOSVNBVElPTl9JRF9JREVOVElGSUVSIn1dfQ==
Example request with userIntoType set to PHONE:

If you wish to initiate a sign request for a user with a phone number '+46731234567':

  1. Create the JSON structure {"userInfoType":"PHONE","userInfo":"+46731234567","title":"Sign transaction","confidential":false,"expiry":1517526000000,"dataToSignType":"SIMPLE_UTF8_TEXT","dataToSign":{"text":"VGhpcyBpcyBhIHRleHQgZm9yIHNpZ24gdHJhbnNhY3Rpb24u"},"signatureType":"SIMPLE"}
  2. Encode the JSON structure to Base64.
  3. Create the HTTP POST request with a POST parameter name initSignRequest and the Base64 encoded JSON structure from the step 2 as its value.

The HTTP body should be the following:

initSignRequest=eyJ1c2VySW5mb1R5cGUiOiJQSE9ORSIsInVzZXJJbmZvIjoiKzQ2NzMxMjM0NTY
3IiwidGl0bGUiOiJTaWduIHRyYW5zYWN0aW9uIiwiY29uZmlkZW50aWFsIjpmYWxzZSwiZXhwaXJ5Ij
oxNTE3NTI2MDAwMDAwLCJkYXRhVG9TaWduVHlwZSI6IlNJTVBMRV9VVEY4X1RFWFQiLCJkYXRhVG9Ta
WduIjp7InRleHQiOiJWR2hwY3lCcGN5QmhJSFJsZUhRZ1ptOXlJSE5wWjI0Z2RISmhibk5oWTNScGIy
NHUifSwic2lnbmF0dXJl
VHlwZSI6IlNJTVBMRSJ9
Example request with userIntoType set to SSN:

If you wish to initiate a sign request for a user with an SSN '198905218072' and country 'SE':

  1. Create the JSON structure {"country":"SE","ssn":"198905218072"}, then do the base64 of this JSON.
  2. This is the Base64 of step 1:   'eyJjb3VudHJ5IjoiU0UiLCJzc24iOiIxOTg5MDUyMTgwNzIifQ==' , which is the userInfo value in our request.
  3. Create the JSON structure {"userInfoType":"SSN","userInfo":"eyJjb3VudHJ5IjoiU0UiLCJzc24iOiIxOTg5MDUyMTgwNzIifQ==","title":"Sign transaction","expiry":1517526000000,"dataToSignType":"SIMPLE_UTF8_TEXT","dataToSign":{"text":"VGhpcyBpcyBhIHRleHQgZm9yIHNpZ24gdHJhbnNhY3Rpb24u"},"signatureType":"SIMPLE"}
  4. Encode the JSON structure to Base64.
  5. Create the HTTP POST request with a POST parameter name initSignRequest and the Base64 encoded JSON structure from the step 4 as its value.

The HTTP body should be the following:

initSignRequest=eyJ1c2VySW5mb1R5cGUiOiJTU04iLCJ1c2VySW5mbyI6ImV5SmpiM1Z1ZEhKNU
lqb2lVMFVpTENKemMyNGlPaUl4T1RnNU1EVXlNVGd3TnpJaWZRPT0iLCJ0aXRsZSI6IlNpZ24gdHJh
bnNhY3Rpb24iLCJleHBpcnkiOjE1MTc1MjYwMDAwMDAsImRhdGFUb1NpZ25UeXBlIjoiU0lNUExFX1
VURjhfVEVYVCIsImRhdGFUb1NpZ24iOnsidGV4dCI6IlZHaHBjeUJwY3lCaElIUmxlSFFnWm05eUlI
TnBaMjRnZEhKaGJuTmhZM1JwYjI0dSJ9LCJzaWduYXR1cmVUeXBlIjoiU0lNUExFIn0=



Possible errors returned by the method are the following:

Return code
Explanation
1001Invalid or missing userInfoType.
1002Invalid or missing userInfo.
1004You are not allowed to call this method.
1005User has disabled your service.
1006Invalid confidential.
1008Unknown Relying Party.
1009You are not allowed to request integratorSpecificUserId parameter.
1010JSON request cannot be parsed.
1012User with the specified userInfo does not exist in Freja eID database.
3000Invalid or missing dataToSignType.
3001Invalid or missing dataToSign.
3002Invalid or missing signatureType.
3003Invalid expiry time.
3004Invalid push notification.
3005Invalid attributesToReturn parameter.
3006Custom identifier has to exist when it is requested.
3007Invalid transaction title.
4001In order to use organisational transactions, user must have an Organisation ID set. 
4007Invalid organisation id issuer.


If HTTP 200 is returned from the method, the following return value will be present in the body of the response:

JSON Response Value in body
{
   "signRef":"Reference to be submitted in getOneResult method"
}

signRef: String, mandatory. A reference unique to the transaction, that can be used to query the result of a specific signing transaction (see Signature in Organisation ID Service#Get one signature result method and Signature in Organisation ID Service#Get signature results method below).


Methods for retrieving signature results

There are two methods that can be used for fetching digital signature results: one that returns a single result for a specified signature reference (signRef returned from a call to Initiate sign method), and one that returns multiple signature results. The latter is the preferred way of fetching results in situations where a Relying Party has many concurrent signatures in progress, as it reduces the number of polling requests.

Get one signature result method

The method is called using HTTP POST through the URLs below:

System
Method endpoint
Test
https://services.test.frejaeid.com/organisation/sign/1.0/getOneResult
Production
https://services.prod.frejaeid.com/organisation/sign/1.0/getOneResult


The parameter of the method is a Base64 UTF8-encoded JSON payload according to the following:

Parameter name
Value
getOneSignResultRequest
{
   "signRef":"Signature reference"
}

signRef: String, mandatory. The value must be equal to a signature reference previously returned from a call to the Initiate sign method. The time period during which a specific signature reference is available for checking will depend on the longevity of the signature operation (see the expiry parameter in the Initiate sign method) and is calculated as expiry time plus 3 days.

Example request:

If you wish to fetch a single signature result with the signature reference previously returned from a call to initSignRequest (for a user with specific organisation identifier 'vejobla'), follow these steps:

  1. Create the JSON structure {"signRef":"TrLA9zdxCBlNOQNvkdhAM14mJmlL20digC7+QgEVRwmE7SH8Qm0swWIc6whfKm4Y"}
  2. Encode the JSON structure to Base64.
  3. Create the HTTP POST request with a POST parameter name getOneSignResultRequest and the Base64 encoded JSON structure from the step 2 as its value.

The HTTP body should be the following (compact format, line broken for clarity only):

getOneSignResultRequest=eyJzaWduUmVmIjoiVHJMQTl6ZHhDQmxOT1
FOdmtkaEFNMTRtSm1sTDIwZGlnQzcrUWdFVlJ3bUU3U0g4UW0wc3dXSWM2d2hmS200WSJ9


Possible errors returned by the method are the following:

Return code
Explanation
1008Unknown Relying Party.
1100Invalid reference (for example, nonexistent or expired).


If HTTP 200 is returned from the method, the following return value will be present in the body of the response:


JSON Response Value in body
Response body
{
   "signRef":"Signature reference",
   "status":"Signature status",
   "details":"Signed data, see below",
   "requestedAttributes":{
      "basicUserInfo":{
         "name":"User's name",
         "surname":"User's surname"
      },
      "emailAddress":"User's primary email address",
      "allEmailAddresses":[
         {
            "emailAddress":"User's email address"
         },
         {
            "emailAddress":"User's email address"
         }
      ],
	"allPhoneNumbers":[
        {
            "phoneNumber":"User's phone number"
        },
        {
            "phoneNumber":"User's phone number"
        }
      ],    
      "dateOfBirth":"User's date of birth",
      "age":"User's age",
      "photo":"User's photo",
      "addresses":[
         {
            "country":"Country",
            "city":"City",
            "postCode":"Postal code",
            "address1":"Street, number or equivalent",
            "address2":"Street, number or equivalent",
            "address3":"Street, number or equivalent",
            "validFrom":"Date from which the address is valid",
            "type":"Type of user's address",
            "sourceType":"Source from which the address is obtained"
         }
      ],
      "ssn":{
         "ssn":"Social security number of the end user",
         "country":"Country of SSN"
      },
      "document" : {
         "type":"Type of document used for registration e.g. passport",
         "country":"Document issuing country",
         "serialNumber":"Document serial number",
         "expirationDate":"Document expiration date"
      },
      "registrationLevel":"User's registration level in Freja eID",
      "organisationIdIdentifier":"Custom organisation attribute",
      "organisationId":{
               "identifier":"Custom organisation attribute",
               "issuerFriendlyName":{
                    "EN":"localised issuer friendly name",                          
                    "SV":"localised issuer friendly name"},
              "issuerCode": "organisation code",
              "additionalAttributes":["OrganisationIdAttribute":{
                                          "key":"attribute_key",
                                          "value":"attribute_value",
                                          "displayText":"attribute_name"}
                                     ]
       },
      "relyingPartyUserId":"Unique user ID reserved for Relying Parties",
      "integratorSpecificUserId":"Unique user ID reserved for Integrators",
      "customIdentifier":"Custom identifier set by the RP",
      "covidCertificates":{
            "vaccines": {
                "certificate": "User's vaccine data"
             },
            "tests": {
                "certificate": "User's test data"
             },
            "recovery": {
                "certificate": "User's recovery data"
             },
            "allowed": true/false
            } 
    }
}

signRef: String, mandatory . The signature reference of the signing request.

status: String, mandatory. One of:

  • STARTED (the transaction has been started but not yet delivered to Freja eID application associated with the end user),
  • DELIVERED_TO_MOBILE (the Freja eID app has downloaded the transaction),
  • CANCELED (the end user declined the signature request), 
  • RP_CANCELED (the sign request was sent to the user but canceled by the RP before the user could respond),
  • EXPIRED (the signature request was not approved by the end user within the signature validity limit as requested when the signature was initialised),
  • APPROVED (the signature was successful).

details: A signed object (see below), optional. Provides details and evidence of the signing if status was equal to APPROVED.

requestedAttributes: JSON object  (see below), optional. Provides additional attributes about a user if required in attributesToReturn parameter in related initSignRequest and the status was equal to APPROVED. 

details

The content of this response element will depend on the signatureType requested when the signature was initiated. For a Simple signature type, it will contain a JWS in compact serialised form as following:

BASE64URL(UTF8(JWS Protected Header)) || ’.’ || BASE64URL(JWS Payload) || ’.’ || BASE64URL(JWS Signature)


JWS Protected Header

{
   "x5t":"SHA-1 digest of the signing certificate",
   "alg":"algorithm used to secure the JWS"
}

x5t: Mandatory, Base64URL encoding of the certificate's SHA-1 digest.
alg: Mandatory, the value shall be RS256 which corresponds to 'RSA PKCS#1 signature with SHA-256'.


JWS Payload

{
   "signRef":"Signature reference",
   "status":"Signature status",
   "userInfoType":"User info type",
   "userInfo":"User information corresponding to user info type",
   "minRegistrationLevel":"Minimum registration level of user",
   "timestamp":"Time when signature was confirmed by end user",
   "signatureType":"Signature type",
   "signatureData":{
      "userSignature":"The signature produced by the end user",
      "certificateStatus":"Evidence of end-users certificate status"
   },
   "requestedAttributes":{
      JSON object, see below.
    }
}

signRef: See signRef above.

status: See status above.

userInfoType: See userInfoType as described in Initiate sign method.

userInfo: See userInfo as described in Initiate sign method.

minRegistrationLevel:  Minimum registration level of a user required by the Relying Party when the Organisation ID was added.

timestamp: Long, mandatory. Describes the time when the confirmation by the end user was validated on Freja eID server side. Expressed in milliseconds, since January 1, 1970, 00:00 UTC.

signatureType: String, mandatory. The type of signature that is requested. Currently SIMPLE and EXTENDED are supported.

signatureData: See fields below, mandatory.

userSignature: The produced signature, string, mandatory. Contains the end user's signature in the requested format. The end user's signature will implicitly contain the dataToSign as requested in Initiate sign method as within its payload.

certificateStatus: Base64 string, mandatory. Contains the OCSP response regarding the state of the end-user certificate at the time of validating the signature.

requestedAttributes: JSON object (see below), optional. Provides additional attributes about a user if required in attributesToReturn parameter in related initSignRequest and the status was equal to APPROVED.

requestedAttributes

attributesToReturn: list of objects, optional. When retrieving results, additional information about the user can be returned based on the type of attributes required through this parameter. Each object should contain one attribute. Currently supported attribute types are:

  • BASIC_USER_INFO (name and surname), 
  • EMAIL_ADDRESS (user's primary email address),

    If you would prefer an email with a specific email domain please get in touch with partnersupport@frejaeid.com.

  • ALL_EMAIL_ADDRESSES (all user's email addresses),
  • ALL_PHONE_NUMBERS (all user's phone numbers),
  • DATE_OF_BIRTH (date of birth),

  • AGE (user's age based on their date of birth),
  • PHOTO (user's photo, Base64 encoded PNG bytes),
  • ADDRESSES (user's current addresses),
  • SSN (social security number and country),
  • DOCUMENT (information about the document used for registration),
  • REGISTRATION_LEVEL (the user's registration level in Freja eID),
  • ORGANISATION_ID_IDENTIFIER (specific organisation identifier set for the end user by the Relying Party through the Organisation ID Service), 
  • ORGANISATION_ID (specific organisation identifier set for the end user by the Relying Party, relying party localised (EN and SV) friendly name, relying party organisation code and additional attributes),
  • RELYING_PARTY_USER_ID (a unique, user-specific value that allows the Relying Party to identify the same user across multiple sessions),
  • INTEGRATOR_SPECIFIC_USER_ID (a unique, user-specific value that allows the Integrator to identify the same user across multiple sessions regardless of the Integrated Relying Party service that the user is using. For more info, see Integrator Relying Party Management),
  • CUSTOM_IDENTIFIER (a unique, Relying Party-specific, user identifier, set by the Relying Party through the Custom Identifier Management)


Get signature results method

The method is called using HTTP POST through the URLs below:

System
Method endpoint
Test
https://services.test.frejaeid.com/organisation/sign/1.0/getResults
Production
https://services.prod.frejaeid.com/organisation/sign/1.0/getResults


The parameter of the method is a Base64 UTF8-encoded JSON payload according to the following:

Parameter name
Value
getSignResultsRequest
{
   "includePrevious":"Include previously returned results"
}

includePrevious: String, mandatory. Must be equal to ALL. Indicates that the complete list of signature requests is successfully initiated by the Relying Party. The time period during which a specific signature reference is available for checking will depend on the longevity of the signature operation (see the expiry parameter in the Initiate sign method) and is calculated as expiry time plus 3 days.

Example request:

If you wish to fetch multiple signature results, follow these steps:

  1. Create the JSON structure {"includePrevious":"ALL"}
  2. Encode the JSON structure to Base64.
  3. Create the HTTP POST request with a POST parameter name getSignResultsRequest and the Base64 encoded JSON structure from the step 2 as its value.

The HTTP body should be the following:

getSignResultsRequest=eyJpbmNsdWRlUHJldmlvdXMiOiJBTEwifQ==


Possible errors returned by the method are the following:

Return code
Explanation
1008Unknown Relying Party.
1200Invalid or missing includePrevious parameter.


If HTTP 200 is returned from the method, the following return value will be present in the body of the response:


JSON Response Value in body
Response body
{
   "signatureResults":[
      {
         "signRef":"Signature reference",
         "status":"Signature status",
         "details":"Signed data, see below",
         "requestedAttributes":{
            "basicUserInfo":{
               "name":"User's name",
               "surname":"User's surname"
            },
            "emailAddress":"User's primary email address",
            "allEmailAddresses":[
               {
                  "emailAddress":"User's email address"
               },
               {
                  "emailAddress":"User's email address"
               }
            ],
			"allPhoneNumbers":[
        	  {
            	"phoneNumber":"User's phone number"
        	  },
        	  {
            	"phoneNumber":"User's phone number"
        	  }
      		],    
            "dateOfBirth":"User's date of birth",
            "age":"User's age",
            "photo":"User's photo",        
            "addresses":[
               {
                  "country":"Country",
                  "city":"City",
                  "postCode":"Postal code",
                  "address1":"Street, number or equivalent",
                  "address2":"Street, number or equivalent",
                  "address3":"Street, number or equivalent",
                  "validFrom":"Date from which the address is valid",
                  "type":"Type of user's address",
                  "sourceType":"Source from which the address is obtained"
               }
            ],
            "ssn":{
               "ssn":"Social security number of the end user",
               "country":"Country of SSN"
            },
            "document" : {
               "type":"Type of document used for registration e.g. passport",
               "country":"Document issuing country",
               "serialNumber":"Document serial number",
               "expirationDate":"Document expiration date"
            },
            "registrationLevel":"User's registration level in Freja eID",
            "organisationIdIdentifier":"Custom organisation attribute",
            "organisationId":{
               "identifier":"Custom organisation attribute",
               "issuerFriendlyName":{
                    "EN":"localised issuer friendly name",                          
                    "SV":"localised issuer friendly name"},
              "issuerCode": "organisation code",
              "additionalAttributes":["OrganisationIdAttribute":{
                                          "key":"attribute_key",
                                          "value":"attribute_value",
                                          "displayText":"attribute_name"}
                                     ]
            },
            "relyingPartyUserId":"Unique user ID reserved for Relying Parties",
            "integratorSpecificUserId":"Unique user ID reserved for Integrators",
            "customIdentifier":"Custom identifier set by the RP",
            "covidCertificates":{
               "vaccines": {
                  "certificate": "User's vaccine data"
                },
               "tests": {
                  "certificate": "User's test data"
               },
               "recovery": {
                  "certificate": "User's recovery data"
               },
              "allowed": true/false
            }   
          }
      },
      {
         "signRef":"..."
      }
   ]
}

signatureResults: An array of JSON objects, mandatory. An array of signature result objects (if the signatureRef parameter was passed, the array will always be of length 1).

signRef: String, mandatory . The signature reference of the signing request.

status: String, mandatory. One of:

  • STARTED (the transaction has been started but not yet delivered to Freja eID application associated with the end user),
  • DELIVERED_TO_MOBILE (the Freja eID app has downloaded the transaction),
  • CANCELED (the end user declined the signature request),
  • RP_CANCELED (the sign request was sent to the user but canceled by the RP before the user could respond),
  • EXPIRED (the signature request was not approved by the end user within the signature validity limit as requested when the signature was initialised),
  • APPROVED (the signature was successful).

details: A signed object, optional. Provides details and evidence of the signature if status was equal to APPROVED (see details as described in the Signature in Organisation ID Service#Get one signature result method above).

requestedAttributes: JSON object (see details as described in the Get one signature result method above), optional.


Cancel sign method

This method is used by a Relying Party to cancel a signature request.

The method is called using HTTP POST through the URLs below:

System
Method endpoints
Test
https://services.test.frejaeid.com/organisation/sign/1.0/cancel
Production
https://services.prod.frejaeid.com/organisation/sign/1.0/cancel


The parameter of the method is a Base64 UTF8-encoded JSON payload according to the following:

Parameter name
Value
cancelSignRequest
{
   "signRef":"Signature reference"
}

signRef: string, mandatory . The value must be equal to a signature reference previously returned from a call to the Initiate sign method.

Example request:

If you wish to cancel a sign request, follow these steps:

  1. Create the JSON structure {"signRef":"TrLA9zdxCBlNOQNvkdhAM14mJmlL20digC7+QgEVRwmE7SH8Qm0swWIc6whfKm4Y"}
  2. Encode the JSON structure to Base64.
  3. Create the HTTP POST request with a POST parameter name cancelSign and the Base64 encoded JSON structure from the step 2 as its value.

The HTTP body should be the following (line broken for clarity only):

cancelSignRequest=eyJzaWduUmVmIjoiVHJMQTl6ZHhDQmxOT1FOdmtkaEFNMTRtSm1sTDIwZGlnQzcr
UWdFVlJ3bUU3U0g4UW0wc3dXSWM2d2hmS200WSJ9


Possible errors returned by the method are the following:

Return code
Explanation
1004You are not allowed to call this method.
1008Unknown Relying Party.
1100Invalid reference (for example, nonexistent or expired).

If HTTP 200 is returned from the method, the request was successfully fulfilled.