https://services.test.frejaeid.com/authentication/1.0/initAuthentication

https://services.prod.frejaeid.com/authentication/1.0/initAuthentication

{
   "userInfoType":"User info type",
   "userInfo":"User information corresponding to user info type",
   "attributesToReturn":
     [
        {
           "attribute":"Type of attribute to be returned"
        }
     ],
   "restrict":"Restricts the login request to a specific mobile device",
   "minRegistrationLevel":"Minimum required registration level of a user"
}

userInfoType: string, mandatory. Describes the type of user information supplied to identify the end user. Currently one of: PHONE (end user's telephone number), EMAIL (end user's email), SSN (end user's social security number), CUST (a custom identifier), 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. For more details please see Implementation - Best Practices.

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 SSN, then it must be a Base64 encoding of the ssnuserinfo JSON structure described below. If userInfoType is CUST, then see custuserinfo 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 email address), DATE_OF_BIRTH (date of birth), CUSTOM_IDENTIFIER (a unique, RP-specific, user identifier, set by the RP through the Custom Identifier Management), SSN (social security number and country ), RELYING_PARTY_USER_ID (a unique, user-specific value that allows the Relying Party to identify the same user across multiple sessions).

restrict: base64 string, optional. A value that restricts the login action only to the Freja eID mobile application started with the same parameter. This can be used in situations where the relying party service is accessed through a browser or app on the same device as the Freja eID app. By passing the same restrict value to the initAuthRequest as to the start of the mobile application, the relying party application can target the usage of the Freja eID on the same device. If present, max 64 characters (post Base64 encoding).

minRegistrationLevel: string, optional. Minimum required registration level of a user in order to approve/decline authentication. Can be BASIC, EXTENDED or PLUS. If not present, default level will be BASIC.

{
"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, must be equal to "SE".
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.

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

1. Create the JSON structure {"userInfoType":"EMAIL","userInfo":"joe.black@verisec.com","minRegistrationLevel":"PLUS","attributesToReturn":[{"attribute":"BASIC_USER_INFO"},{"attribute":"SSN"}]}
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=eyJ1c2VySW5mb1R5cGUiOiJFTUFJTCIsInVzZXJJbmZvIjoiam9lLmJsYWNrQHZlcmlzZWMuY29tIiwibWluUmVnaXN0cmF0aW9uTGV2Z
WwiOiJQTFVTIiwiYXR0cmlidXRlc1RvUmV0dXJuIjpbeyJhdHRyaWJ1dGUiOiJCQVNJQ19VU0VSX0lORk8ifSx7ImF0dHJpYnV0ZSI6IlNTTiJ9XX0=

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

1. Create the JSON structure {"userInfoType":"PHONE","userInfo":"+46731234567","minRegistrationLevel":"BASIC"}
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=eyJ1c2VySW5mb1R5cGUiOiJQSE9ORSIsInVzZXJJbmZvIjoiKzQ2NzMxMjM0NTY3IiwibWluUmVnaXN0cmF0aW9uTGV2ZWwiOiJCQVNJQyJ9

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==", "minRegistrationLevel":"PLUS"}
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=eyJ1c2VySW5mb1R5cGUiOiJTU04iLCJ1c2VySW5mbyI6ImV5SmpiM1Z1ZEhKNUlqb2lVMFVpTENKemMyNGlPaUl4T1RnNU1EVXlNVGd3TnpJ
aWZRPT0iLCAibWluUmVnaXN0cmF0aW9uTGV2ZWwiOiJQTFVTIn0=

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 4 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 Get authentication results method below).

https://services.test.frejaeid.com/authentication/1.0/getOneResult

https://services.prod.frejaeid.com/authentication/1.0/getOneResult

{
   "authRef":"Authentication reference"
}

authRef: string, mandatory . The value must be equal to an authentication reference previously returned from a call to the 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 Initiate authentication method that returned the said reference.

If you wish to fetch an authentication result with the authentication reference previosly returned from a call to initAuthRequest (for a user with an email address joe.black@verisec.com), 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 email address",
      "dateOfBirth":"User's date of birth",
      "customIdentifier":"Custom identifier set by the RP",
	  "ssn":{
			  "ssn":"Social security number of the end user",
			  "country":"Country of SSN"
			},
	  "relyingPartyUserId": "Unique user ID reserved for Relying Parties"
    },
   "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) or 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 required registration level of a user",
   "requestedAttributes":
    {
       "basicUserInfo":{
                        "name":"User's name",
                        "surname":"User's surname"
                       },
       "emailAddress":"User's email address",
       "dateOfBirth":"User's date of birth",
       "customIdentifier":"Custom identifier set by the RP",
	   "ssn":{
			  "ssn":"Social security number of the end user",
			  "country":"Country of SSN"
			 },
	   "relyingPartyUserId":"Unique user ID reserved for Relying Parties"
    },
   "timestamp":"Time when authentication confirmed by end user"
}

authRef: See authRef above.

status: See status above.

userInfoType: See userInfoType as described in Initiate authentication method.

userInfo: See userInfo as described in Initiate authentication method.

minRegistrationLevel: See minRegistrationLevel as desribed in Initiate authentication method.

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.

See above.

See above.

"authRef":"12345-67890-abcdef"
"status":"APPROVED"
"userInfoType":"EMAIL"
"userInfo":"john.doe@somedomain.com"
''requestedAttributes": {"basicUserInfo":{"name":"John","surname":"Doe"}, ''customIdentifier'':''vejodoe'',
"ssn":{"ssn":"198511170040","country":"SE"}
"timestamp":"12345-67890-abcdef" 

(header omitted for brevity)

eyJ1c2VySW5mbyI6ImpvaG4uZG9lQHNvbWVkb21haW4uY29tIiwicmVxdWVzdGVkQXR0cmlidXRlcyI6eyJjdXN0b21JZGVudGlmaWVy
IjoidmVqb2RvZSIsImJhc2ljVXNlckluZm8iOnsic3VybmFtZSI6IkRvZSIsIm5hbWUiOiJKb2huIn0sInNzbiI6eyJjb3VudHJ5Ijoi
U0UiLCJzc24iOiIxOTg1MTExNzAwNDAifSwiaW50ZWdyYXRvclNwZWNpZmljVXNlcklkIjoiODc2NGpnc2Y3ODNnc2sifSwidXNlcklu
Zm9UeXBlIjoiRU1BSUwiLCJhdXRoUmVmIjoiMTIzNDUtNjc4OTAtYWJjZGVmIiwic3RhdHVzIjoiQVBQUk9WRUQiLCJ0aW1lc3RhbXAi
OjE0OTEzODgxNjMzODl9.qEF5K4VRvuKc4VCoc4jBVY5bkqgrPKyEyVPe6eZoUh_mE9DVK_p2cldyKsVfEmKHqKFdKQyuEweS39lm20Q
2NlZq6kBgUb7C3AGR8Mlx-e0iAM2wlLqkQ6ke_U-42Y9G8m8PaWKNvOmSs8K_cfWGzNUsA5EzvNNJGljsdXWXR9Y3cFxzYg5tiwVlRQJ
bJIdsuiOa7aP1JlOVZIa6T7Fz2jCxdtC0qaJBlIq3jZwz16mQHITyuWqf3kQfzJ8QiI9qJpF0U7B8fiSM9cLCP0kAVDd1ZVgChQnN8vv
q6VjRbVySPTQUA7NBELd578ErFk_DcsvAGPnPR66DQnNqLI4taA

https://services.test.frejaeid.com/authentication/1.0/getResults

https://services.prod.frejaeid.com/authentication/1.0/getResults

{
   "includePrevious":"Include previously returned results"
}

includePrevious: string, mandatory. Must be equal to ALL or OUTSTANDING_AND_NEW. If equal to ALL, indicates that the complete list of authentications successfully initiated by the relying party within the last 10 minutes will be returned, including results for previously completed authentication results that have been reported through an earlier call to one of the methods for getting authentication results. Sending OUTSTANDING_AND_NEW as the value will return only the status of outstanding (i.e. authentications still in progress) and completed but previously unreported statuses.

If you wish to fetch multiple authentication 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 getAuthResultsRequest and the Base64 encoded JSON structure from the step 2 as its value.

The HTTP body should be the following:

getAuthResultsRequest=eyJpbmNsdWRlUHJldmlvdXMiOiJBTEwifQ==

{
"authenticationResults":[
    {
      "authref":"Authentication reference",
      "status":"Authentication status",
      "relyingPartyUserId":"Unique user ID reserved for Relying Parties",
      "details":"JWS signed data, see below",
      "requestedAttributes":
        {
          "basicUserInfo":{
                        	"name":"John",
                        	"surname":"Doe"
                      	  },
          "emailAddress":"john.doe@somedomain.com",
          "dateOfBirth":"1987-10-18",
          "customIdentifier":"vejodoe",
 	      "ssn":{
	          		"ssn":"198710180040",
	          		"country":"SE"
	            },
          "relyingPartyUserId": "94039a98c8d"
        },
    },
    {
      "authref":...
    }
  ]
}

authenticationResults: an array of JSON objects, mandatory. An array of authentication result objects (if the authRef parameter was passed, the array will always be of length 1).

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 canceled 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) or REJECTED (e.g. if you try to run more than one authentication transaction for the same user at the same time).

details: JWS signed object (see details as described in the Get one authentication result method above), optional.

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

https://services.test.frejaeid.com/authentication/1.0/cancel

https://services.prod.frejaeid.com/authentication/1.0/cancel

{
   "authRef":"Authentication reference"
}

authRef: string, mandatory . The value must be equal to an authentication reference previously returned from a call to the Initiate authentication method.

If you wish to fetch multiple authentication results, 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 cancelAuth 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):

cancelAuthRequest=eyJhdXRoUmVmIjoiR09IUHlKY29LTEorektDRXk0YWJpNmpPTytxNVZLK1MxK1VP
NU9YUm1PUHU0Mml4dlZuc1ZnczdBRFlVZkc4bSJ9