{
   "userInfoType":"User info type",
   "userInfo":"User information corresponding to user info 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 (the user need not enter any identifier, their identity will be determined as a result of the authentication process). The INFERRED method is typically used in conjunction with QR codes.
  

userInfo: string, mandatory, 256 characters maximum. If the userInfoType is ORG_ID, interpreted as a string value of the specific organisation identifier set for the end user. 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 SSN, then it must be a Base64 encoding of the ssnuserinfo JSON structure described below. If userInfoType is INFERRED, then userInfo must be set to: "N/A" because there is no data for the user to enter (see example below).

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.

{
   "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.

If you wish to initiate authentication request for a user with an email address joe.black@verisec.com and request their name, surname, SSN and organisation identifier, follow these steps:

1. Create the JSON structure {"userInfoType":"EMAIL","userInfo":"joe.black@verisec.com","attributesToReturn":[{"attribute":"BASIC_USER_INFO"},{"attribute":"SSN"},{"attribute":"ORGANISATION_ID_IDENTIFIER"}]}
2. Encode the JSON structure to Base64.
3. Create the HTTP POST request with a POST parameter name initAuthRequest 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):

initAuthRequest=eyJ1c2VySW5mb1R5cGUiOiJFTUFJTCIsInVzZXJJbmZvIjoiam9lLmJsYWNrQHZ
lcmlzZWMuY29tIiwiYXR0cmlidXRlc1RvUmV0dXJuIjpbeyJhdHRyaWJ1dGUiOiJCQVNJQ19VU0VSX0
lORk8ifSx7ImF0dHJpYnV0ZSI6IlNTTiJ9LHsiYXR0cmlidXRlIjoiT1JHQU5JU0FUSU9OX0lEX0lER
U5USUZJRVIifV19

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

1. Create the JSON structure {"userInfoType":"PHONE","userInfo":"+46731234567"}
2. Encode the JSON structure to Base64.
3. Create the HTTP POST request with a POST parameter name initAuthRequest and the Base64 encoded JSON structure from the step 2 as its value.

The HTTP body should be the following:

initAuthRequest=eyJ1c2VySW5mb1R5cGUiOiJQSE9ORSIsInVzZXJJbmZvIjoiKzQ2NzMxMjM0NTY3In0=

If you wish to initiate authentication 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=="}
4. Encode the JSON structure to Base64.
5. Create the HTTP POST request with a POST parameter name initAuthRequest and the Base64 encoded JSON structure from the step 4 as its value.

The HTTP body should be the following:

initAuthRequest=eyJ1c2VySW5mb1R5cGUiOiJTU04iLCJ1c2VySW5mbyI6ImV5SmpiM1Z1ZEhKNUlq
b2lVMFVpTENKemMyNGlPaUl4T1RnNU1EVXlNVGd3TnpJaWZRPT0ifQ==

If you wish to authenticate a user via a QR code:

1. Create the JSON structure {"userInfoType":"INFERRED","userInfo":"N/A"}
2. Encode the JSON structure to Base64.
3. Create the HTTP POST request with a POST parameter name initAuthRequest and the Base64 encoded JSON structure from the step 2 as its value.

The HTTP body should be the following:

initAuthRequest=eyJ1c2VySW5mb1R5cGUiOiJJTkZFUlJFRCIsInVzZXJJbmZvIjoiTi9BIn0=

{
   "authRef":"Reference to be submitted in getAuthResults method"
}

authRef: string, mandatory. A reference unique to the transaction that can be used to query the result of a specific transaction (see Authentication in Organisation ID Service#Get authentication results method below).

{
   "authRef":"Authentication reference"
}

authRef: string, mandatory . The value must be equal to an authentication reference previously returned from a call to the Authentication in Organisation ID Service#Initiate authentication method. As mentioned above, authentications are short-lived and, once initiated by a Relying Party, must be confirmed by an end user within two minutes. Consequently, fetching the result of an authentication for a given authentication reference is only possible within 10 minutes of the call to Authentication in Organisation ID Service#Initiate authentication method that returned the said reference.

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

1. Create the JSON structure {"authRef":"GOHPyJcoKLJ+zKCEy4abi6jOO+q5VK+S1+UO5OXRmOPu42ixvVnsVgs7ADYUfG8m"}
2. Encode the JSON structure to Base64.
3. Create the HTTP POST request with a POST parameter name getOneAuthResultRequest 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):

getOneAuthResultRequest=eyJhdXRoUmVmIjoiR09IUHlKY29LTEorektDRXk0YWJpNmpPTytxNV
ZLK1MxK1VPNU9YUm1PUHU0Mml4dlZuc1ZnczdBRFlVZkc4bSJ9

{
   "authRef":"Authentication reference",
   "status":"Authentication status",
   "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"
         }
      ],
      "customIdentifier":"Custom identifier set by the RP",
      "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":"Specific organisation identifier",
      "organisationId":{
         "identifier":"User's organisation identifier",
         "issuerFriendlyName":{
                    "EN":" Relying Party Friendly Name",
                    "SV":"Relying Party Friendly Name"},
         "issuerCode":"Organisational 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",
   "details":"JWS signed data, see below"
}

authRef: string, mandatory. The authentication reference of the authentication.

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 authentication request),
• RP_CANCELED (the authentication request was sent to the user but cancelled by the RP before the user could respond),
• EXPIRED (the authentication request was not approved by the end user within the authentication validity limit of two minutes),
• APPROVED (the authentication was successful),
• REJECTED (e.g. if you try to run more than one authentication transaction for the same user at the same time).

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

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

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

{
   "authRef":"Authentication reference",
   "status":"Authentication status",
   "userInfoType":"User info type",
   "userInfo":"User information corresponding to user info type",
   "minRegistrationLevel":"Minimum registration level of user",
   "requestedAttributes":{
      JSON object, see below.   
    },
   "timestamp":"Time when authentication confirmed by end user"
}

authRef: See authRef above.

status: See status above.

userInfoType: See userInfoType as described in Authentication in Organisation ID Service#Initiate authentication method.

userInfo: See userInfo as described in Authentication in Organisation ID Service#Initiate authentication method.

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

requestedAttributes: JSON object, optional. See requestedAttributes below.

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.