Authentication Service

Overview

The Freja eID Authentication Service allows Relying Parties to authenticate end users through the use of the Freja eID mobile application. The end user will have previously downloaded the Freja eID mobile application on one or more devices they possess.

We differentiate between 3 types of users based on assurance of the user's identity.

  1. Basic - for users who have only registered with an email address
  2. Extended - for users whose identity was verified with an ID document (list of supported countries can be seen in the app)
  3. Plus - for users whose identity was further verified with a physical meeting in addition to an ID document (only available in Sweden)

The level of the user allows you to refer to them in different ways (via the userInfoType value). This is important because depending on the userInfoType you implement, that is the identifier that users will have to enter in your login form.

Important information!

This guide is written from the point of view of QR code authentication where the userInfoType is set to INFERRED. This is the method of authentication we recommend as the safest and easiest to implement.

More About QR Code Implementation

Qr code authentication is supported by the Freja eID Authentication service. In essence, a user authenticates themselves by scanning a generated QR code and approving the authentication action. This method is very secure because users must physically be presented with a QR code to scan, otherwise an action cannot be generated in their name.

On mobile the process is even simpler since the user needn't scan a QR code physically. Everything takes place within their device thereby making authentication even more secure because the authentication process is initiated and approved on the same device. In addition, this method is the most user friendly since it foregoes typing in user identifiers (emails, phone numbers etc.).

In summary, we recommend implementing this kind of authentication because:

  • It is much more user friendly, especially on mobile.
  • It is a much safer method of authentication.

This document goes more into depth regarding the Freja eID API. If you would like to see more details QR code login implementation, please refer to this page about Implementation and Best Practices.

Before You Begin

There are several technical requirements that must be in place before implementation can begin. Please refer to the section 'Before You Begin' on this page.

Methods

The Freja eID Relying Party Authentication Service allows you to:

  1. Initiate an authentication request;
  2. Get one authentication result;
  3. Get multiple authentication results;
  4. Cancel an authentication request.

When it comes to getting authentication results, we recommend using the method for multiple results to reduce the number of polling requests.

Initiate authentication method

Use this method to initiate an authentication request. These requests are intended to be used when a user initiates an action to access your online service. Important features of this method are:

  1. Authentication requests are short-lived i.e. from the point of initiation the user has 2 minutes to confirm it via Freja eID;
  2. Only one active authentication request may exist for any given user at any given time. If the user initiates another authentication request either with your or another service, both will be cancelled.

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

EnvironmentEndpoint
Test
https://services.test.frejaeid.com/authentication/1.0/initAuthentication
Production
https://services.prod.frejaeid.com/authentication/1.0/initAuthentication


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

Parameter nameValue
initAuthRequest
{
   "userInfoType":"User info type",
   "userInfo":"User information corresponding to user info type",
   "attributesToReturn":[
      {
         "attribute":"Type of attribute to be returned"
      }
   ],
   "minRegistrationLevel":"Minimum required registration level of a user",
   "userConfirmationMethod":"Method used to confirm user's identity"
}

userInfoType: string, mandatory. Describes the type of user information supplied to identify the end user. For QR code login should be set to INFERRED. Here the user does not type anything, they initiate authentication by using their device to scan the QR code presented to them on the login page of your service.

userInfo: 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).

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.

userConfirmationMethod: string, optional. Used to specify the method by which the user's identity is confirmed when performing an action. Can be DEFAULT or DEFAULT_AND_FACE.

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 JPEG bytes),
  • ADDRESSES (user's current addresses),
  • SSN (social security number and country),
  • DOCUMENT (data from the document used for registration),
  • DOCUMENT_PHOTO (document photo, Base64 encoded JPEG bytes),
  • REGISTRATION_LEVEL (user's registration level in Freja eID)
  • 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 the section about Integrator Relying Party Management),
  • CUSTOM_IDENTIFIER (a unique, Relying Party-specific, user identifier, set by the Relying Party through the Custom Identifier Management),

    In order to be able to request this attribute, you must first get in touch with partnersupport@frejaeid.com.

    If the requested attribute is BASIC_USER_INFO, DATE_OF_BIRTH, AGE, PHOTO, ADDRESSES, SSN, DOCUMENT, DOCUMENT_PHOTO or COVID_CERTIFICATE, the minRegistrationLevel must be set to EXTENDED or PLUS as we do not possess this data for BASIC users.

Example request with the userInfoType set to INFERRED
  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 step 2 as its value.

The HTTP body should be the following:

initAuthRequest=eyJ1c2VySW5mb1R5cGUiOiJJTkZFUlJFRCIsInVzZXJJbmZvIjoiTi9BIn0=

Possible errors returned by the method are the following:

Code ReturnedExplanation
1001Invalid or missing userInfoType.
1002Invalid or missing userInfo.
1003Invalid restrict.
1004You are not allowed to call this method.
1005User has disabled your service.
1007Invalid min registration level.
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.
2000Authentication request failed. Previous authentication request was rejected due to security reasons.
2002Invalid attributesToReturn parameter.
2003Custom identifier has to exist when it is requested.

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

Get one authentication result method

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

EnvironmentEndpoint
Test
https://services.test.frejaeid.com/authentication/1.0/getOneResult
Production
https://services.prod.frejaeid.com/authentication/1.0/getOneResult

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

Parameter nameValue
getOneAuthResultRequest
{
   "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. Because authentications are short-lived, fetching the result of a given authRef is only possible within 10 minutes from the time the initial authentication request was made.

Example request

If you wish to fetch an authentication result with the authentication reference previously returned from a call to initAuthRequest, 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 step 2 as its value.

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

getOneAuthResultRequest=eyJhdXRoUmVmIjoiR09IUHlKY29LTEorektDRXk0YWJpNmpPTytxNV
ZLK1MxK1VPNU9YUm1PUHU0Mml4dlZuc1ZnczdBRFlVZkc4bSJ9

Possible errors returned by the method are the following:

Code returnedExplanation
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 following return value will be present in the body of the response:

JSON response value in body
Response Body
{
   "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, Base64 encoded JPEG bytes",
      "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"
      },
      "documentPhoto":"Document photo, Base64 encoded JPEG bytes",
      "registrationLevel":"User's registration level in Freja eID",
      "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) 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.

details

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":{
       JSON object, see below.   
       },    
      "timestamp":"Time when authentication is confirmed by end user"
}

authRef: See authRef above.

status: See status above.

userInfoType: INFERRED

userInfo: N/A

minRegistrationLevel: See minRegistrationLevel as described 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.

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, Base64 encoded JPEG bytes",
   "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 Relying Party",
   "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"
   },
   "documentPhoto":"Document photo, Base64 encoded JPEG bytes",
   "registrationLevel":"User's registration level in Freja eID",
   "relyingPartyUserId":"Unique user ID reserved for Relying Parties",
   "integratorSpecificUserId":"Unique user ID reserved for Integrators"
}

basicUserInfo: JSON object which contains user's name and surname.

emailAddress: String, representing the user's primary email address.

allEmailAddresses: List of JSON objects which contains all end user's registered email addresses. The list will contain the primary email address and up to 2 other email addresses user might have connected to their account. Email addresses will be randomly sorted. If the user does not have any additional email addresses registered, the list will contain only the primary email address.

allPhoneNumbers:  List of JSON objects which contains all end user's registered phone numbers. This list will contain up to 3 phone numbers the user might have connected to their account. If no phone number is registered for a given user, an empty list will be returned.

dateOfBirth: String containing date of birth in format: YYYY-MM-DD.

age: Integer, calculated based on the date of birth.

photo: String, Base64 encoded JPEG bytes.

addresses: List of JSON objects which contains one or more end user's addresses. If no address is registered for a given user, an empty list will be returned. Each object will contain the following information:

country: String. Contains the ISO-3166 two-alphanumeric country code of the country where the user's address resides.
city: String. City in which the user's address resides.
postCode: String. Postal code of the city or city area in which the user's address resides. 
address 1, 2, 3: String. Up to three lines of address information containing, for example, street and number, house name or apartment number, and ‘care of’ or ‘attention’ designations, area or village clarifications. The number of lines in the response depends on the address information. At least one will be returned. 
validFrom: String. Date from which the address is valid, according to the source of information. Date is returned in format: YYYY-MM-DD (ISO-8601)
type: String. Type of address. Currently, can be RESIDENTIAL or POSTAL. 
sourceType: String. Type of source from which the information about the address has been obtained. Currently, only GOVERNMENT_REGISTRY can be returned. Namely, in the current version of Freja eID, the information about the end user's address is obtained from Statens personadressregister (SPAR) for Sweden and Det Sentrale Folkeregister (DSF) for Norway. 

ssn: JSON object which contains social security number and country.

documentList of JSON objects with information about the user's document used in registration. Each object will contain the following information:

  • type: String. The type of document used during registration abbreviated and returned as: "PASS" (passport), "DRILIC" (driving licence), "NATID" (national ID card), "IDSIS" (SIS-issued ID document), "TAXID" (document issued by the Swedish Tax Authority), and "OTHERID" (any other type of document).
  • countryString. Contains the ISO-3166 two-alphanumeric country code of the issuing country.
  • serialNumber: String representing the document's serial number.
  • expirationDate: String containing the document's expiration date in the format: YYYY-MM-DD.

documentPhoto: String, Base64 encoded JPEG bytes.

registrationLevel: the user's registration level in Freja eID, can be BASIC, EXTENDED or PLUS

relyingPartyUserId: String, mandatory. Represents a unique, user-specific value that allows the Relying Party to identify the same user across multiple sessions.

integratorSpecificUserId: String, represents a unique, user-specific value that allows Integrators to identify the same user across multiple sessions regardless of the Integrated Relying Party service that the user is using. For more info, see the section about Integrator Relying Party Management. 

customIdentifier: String, a unique, Relying Party-specific, user identifier, set by the Relying Party itself through the Custom Identifier Management.

ssn

ssn: string, mandatory. Expected SSN of the end user based on the document added to Freja eID.

  • If country equal to "SE", the value must be the 12-digit format of the Swedish "personnummer" without spaces or hyphens. E.g. 195210131234.
  • If country equal to ''NO'', the value must be the 11-digit format of the Norwegian "personnummer" without spaces or hyphens. E.g. 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. The hyphen can be replaced with the letter A. E.g. 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. E.g. 1310521234.

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'' (Denmark).

Example data for APPROVED response, JSON response body:

{
   "authRef":"12345-67890-abcdef",
   "status":"APPROVED",
   "details":"JWS content as per below",
   "requestedAttributes":{
      "basicUserInfo":{
         "name":"Joe",
         "surname":"Black"
      },
      "emailAddress":"joe.black@frejaeid.com",
      "allEmailAddresses":[
         {
            "emailAddress":"joe.black@frejaeid.com"
         },
         {
            "emailAddress":"joebl@domain.com"
         }
      ],
      "allPhoneNumbers":[
         {
            "phoneNumber":"+4600000000"
         },
         {
            "phoneNumber":"+4611111111"
         }
      ],   
      "dateOfBirth":"1985-11-17",
      "age":"36",
      "photo":"SlBFRyBpbWFnZSBieXRlcyBnb2VzIGhlcmUgLi4u",
      "addresses":[
         {
            "country":"SE",
            "city":"Stockholm",
            "postCode":"11120",
            "address1":"C/O Joe Black",
            "address2":"Visdomsgatan 55",
            "validFrom":"2020-03-19",
            "type":"RESIDENTIAL",
            "sourceType":"GOVERNMENT_REGISTRY"
         },
         {
            "country":"NO",
            "city":"Oslo",
            "postCode":"0001",
            "address1":"P.O. Box 456",
            "validFrom":"2020-03-19",
            "type":"POSTAL",
            "sourceType":"GOVERNMENT_REGISTRY"
         }
      ],
      "ssn":{
         "ssn":"198511170040",
         "country":"SE"
      },
       "document" : {
         "type":"PASS",
         "country":"SE",
         "serialNumber":"XA0000001",
         "expirationDate":"2027-01-01"
      },
      "documentPhoto":"SlBFRyBpbWFnZSBieXRlcyBnb2VzIGhlcmUgLi4u"
      "registrationLevel":"PLUS",
      "relyingPartyUserId":"94039a98c8d",
      "integratorSpecificUserId":"54059a95c8d",
      "customIdentifier":"vejobla"
}

Example data for APPROVED response, JWS payload:

FieldValue
Certificate InfoSee above.
HeaderSee above.
Payload
{
   "authRef":"12345-67890-abcdef",
   "status":"APPROVED",
   "userInfoType":"EMAIL",
   "userInfo":"joe.black@verisec.com",
   "requestedAttributes":{
      "basicUserInfo":{
         "name":"Joe",
         "surname":"Black"
      },
      "emailAddress":"joe.black@verisec.com",
      ...
   },
   "timestamp":1584701027510
}
Final JWS (compact
format, line broken
for clarity only)

eyAiYXV0aFJlZiI6IjEyMzQ1LTY3ODkwLWFiY2RlZiIsICJzdGF0dXMiOiJBUFBST1ZFRCIsICJ1c2VySW5mb1R5cGUiOiJFTU

FJTCIsICJ1c2VySW5mbyI6ImpvZS5ibGFja0B2ZXJpc2VjLmNvbSIsICJyZXF1ZXN0ZWRBdHRyaWJ1dGVzIjp7ICJiYXNpY1

VzZXJJbmZvIjp7ICJuYW1lIjoiSm9lIiwgInN1cm5hbWUiOiJCbGFjayIgfSwgImVtYWlsQWRkcmVzcyI6ImpvZS5ibGFja0B2Z

XJpc2VjLmNvbSIsICJhbGxFbWFpbEFkZHJlc3NlcyI6WyB7ICJlbWFpbEFkZHJlc3MiOiJqb2UuYmxhY2tAdmVyaXNlYy5jb

20iIH0sIHsgImVtYWlsQWRkcmVzcyI6ImpvZWJsQGRvbWFpbi5jb20iIH0gXSwgImFsbFBob25lTnVtYmVycyI6WyB7ICJw

aG9uZU51bWJlciI6Iis0NjAwMDAwMDAwIiB9LCB7ICJwaG9uZU51bWJlciI6Iis0NjExMTExMTExIiB9IF0sICJkYXRlT2ZCaX

J0aCI6IjE5ODUtMTEtMTciLCAiYWdlIjozNiwgImFkZHJlc3NlcyI6WyB7ICJjb3VudHJ5IjoiU0UiLCAiY2l0eSI6IlN0b2NraG9

sbSIsICJwb3N0Q29kZSI6IjExMTIwIiwgImFkZHJlc3MxIjoiQy9PIEpvZSBCbGFjayIsICJhZGRyZXNzMiI6IlZpc2RvbXNnYX

RhbiA1NSIsICJ2YWxpZEZyb20iOiIyMDIwLTAzLTE5IiwgInR5cGUiOiJSRVNJREVOVElBTCIsICJzb3VyY2VUeXBlIjoiR09W

RVJOTUVOVF9SRUdJU1RSWSIgfSwgeyAiY291bnRyeSI6Ik5PIiwgImNpdHkiOiJPc2xvIiwgInBvc3RDb2RlIjoiMDAwMSIsI

CJhZGRyZXNzMSI6IlAuTy4gQm94IDQ1NiIsICJ2YWxpZEZyb20iOiIyMDIwLTAzLTE5IiwgInR5cGUiOiJQT1NUQUwiLCAi

c291cmNlVHlwZSI6IkdPVkVSTk1FTlRfUkVHSVNUUlkiIH0gXSwgInNzbiI6eyAic3NuIjoiMTk4NTExMTcwMDQwIiwgImN

vdW50cnkiOiJTRSIgfSwgInJlZ2lzdHJhdGlvbkxldmVsIjoiUExVUyIsICJyZWx5aW5nUGFydHlVc2VySWQiOiI5NDAzOWE

5OGM4ZCIsICJpbnRlZ3JhdG9yU3BlY2lmaWNVc2VySWQiOiI1NDA1OWE5NWM4ZCIsICJjdXN0b21JZGVudGlmaWVyI

joidmVqb2JsYSIsCiJwaG90byI6ImlWQk9SdzBLR2dvQUFBQU5TVWhFVWdBQUFod0FBQU5nQ0FJQUFBRG9DeVlsQ

UFBQUFYTlNSMElBcnM0YzZRQUFBQVJuUVUxQkFBQ3hqd3Y4WVFVQUFBQUpjRWhaY3dBQURzTUFBQTdEQWNkd

nFHUUFBQ0FoU1VSQlZIaGU3ZDJ4ZFNKTDNzYmhtODNtUUE1S0ExY2hmSTQ4T2NpUkorY0dnS2trQ0VFSmJCYjd3

V2htRUZVTmRIVy8wRUEvNXp6T25ZV0dRbWYvUDdvYWlYLys5My8vQVlBSVVRRWdSbFFBaUJFVkFHSkVCWUFZV

VFFZ1JsUUFpQkVWQUdKRUJZQVlVUUVnUmxRQWlCRVZBR0pFQllBWVVRRWdSbFFBaUJFVkFHSkVCWUFZVVFFZ

1JsUUFpQkVWQUdKRUJZQVlVUUVnUmxRQWlCRVZBR0pFQllBWVVRRWdSLi4uIiwKwqAgwqAgwqAgImNvdmlkQ2V

ydGlmaWNhdGVzIjp7CiJ2YWNjaW5lcyI6IHsKImNlcnRpZmljYXRlIjogIkhDMTpOQ0ZPWE4lVFNNQUhOLUhWTjhKN1V

RTUo0LzNSWkxNNTJYR1AxV0cyRDU4KklYRjU5NVRYUjM4V0FCUk1CNTdGLzhYKkczTTlKVVBZMEJaVzQ6LkE2M0

hOTlZSKkcwQzdQSEJPMzNSVzA1TEJQT0YgUVRZRjM0SEdPSUggOEwrNkgxU0YrNUYvM0UxSkFGLjc1IEpEWEkwM

0w5Wkk0UTUlSDBBTjhDSjBQWkJJVEhQK1BSUk1KVlVNIEkvUFNNJUdBOElNJU8lS0kqVzAgLlVRKk4gUlAtK1IyWUJ

WNDRDJEJYR0RPOTg6MExQSE42RDdMTEsqMkg5LTg5VVYtMEwvOklTLU86UzlVWjQrRkpFIDRZM0xML0lJIDBPQz

lTWDArKkI4NVQlNjIqNVBaRDVDQzlUMEglOks1UU5YL0dKWklJN0pTVE5COTUrMTZMRVRGNE4uU1MuUEtJWFIuVUl

BWVVIMldWUUkwVEhYWlEuSjkxIEZJJUIyTEc3UEclIEIvVUkyWVU1TUFYU0crVzM0UElRSkFaR0EyOlVHJVUyRTRBU05

NSDhNLTQwNUExT0stVUtWQ0ZCM0xCLjZESlBIQlMxNUMvS05LTTQkSUlYKkIxSlM5QUM5OU5FN1BIVFJPKzJJKjVDN

kVBMlUkIDhDMlNUIElFJU4xKzI0VjdMRDFMWkJBTUFTMzA2V0RPMSIKfSwKInRlc3RzIjogeyJjZXJ0aWZpY2F0ZSI6Ikh

DMTpOQ0ZPWE4lVFNNQUhOLUgzTzQ6UFZIIEFKMkokOUowSUk2WUogNDNTTEcvRUJORzJONEZCT00kVjQ6TlFBI

E06VUMqR1BYUzRNWktIWkEgS0U3RUMxIDNLOUxUNEQ0JUsqKklSMUwlOktFVjQ5OVRFVzYzWkNEN0xVWjIzNEpUU

FZGSEhCWTRPLU8wRzEzSEgwLUslSUg3WTQvWDg2TU9CJVJIRE0uLUI2L0QwSkFRVFU4RDIlSDBBTjhTSjA2WUJVU0

1BTDg6SjVTSDYtRzkqRTkuJDA1RzkwRjNIWkk1VkElM0tRWUpYMUo6TksyQURWVEFBWkk2NkogT0tRTUkwT0lTVkJGT

0pWVEExSEEtWElSQ0kgT0slSUo1UUJQN0pVN0JKWUoqSUo1T0ktWUlFNDZPOTNYTVI6IEtTJE45SFM1LVFKK1BBK1FJ

JUs0JE43Qk1JK1FWJU40K084JU1NRzI5QUY2TEZCODFRTUtRK01OL1ExOVFFOFEgUE9ET0YkNlJOUVEzWTc0WEwxL

0xKTzlVVU0gUVVRL01OOjQzNTYqQlckJUwrLUpOLk4gTFRCV081OlFOK0EzMVVLWFBST1NOUFMrRFdHREk4RUglMkx

VSTJPL0VHWUlZUzJHU1MlOFMvNDBBUUNJMiJ9LAoicmVjb3ZlcnkiOiB7ICJjZXJ0aWZpY2F0ZSI6IkhDMTpOQ0ZPWE4

lVFNNQUhOLUhGTjRUVEM0IFNKV0taKjlHQkguIE1VOTY1SFJMWDgzTFE1NVVUU0pWUU9JVlVLMUpaWlBRQTNEUDRP

VzYzMUFYNVFNOUlGWTFPU01OVjFMOFZORjZBWU1FMEY6TkUzS1VEOjEzWk01OjZFTDZFJTYwVDkzMlEuUlRSSDkvV

VBORjY3SjZRVzZPVlFPUjYrRzkwLkctUjU0VzEuVUkyUEhVSUUgJDRaSkoqJUNOMVRUQjVDLU9URjFKKjNURkgyVjQyRj

FDT1QkSEZDKklVWjQrRkpFIDRZM0xML0lJIDBISlA3TlZERUIxMkpEKjJEMEhINzgkWkoqREpXUDQyVzU6WVBISlVUUk0

4T0k5WU8gTEUzVVE1TUExVEg4TDJDUElHU1VIUE1VK1ZBV08yTzhVK1ZIKkZZWlEgSDk5MlcgJUpNU0dVVlBRUkhJW

TErIEgxTzE2UDMqN1VGLkpKOEM3WEIvT0lGRDY1KlYwV0kqOVVVM0VKWVJKWDVINFU2OlYrWVRHUUZPUEU2WFZW

JUxUVUtJN1VQRkRDUVUkSlZGOENROjVFOFVPSFIlK1YvRkM5KjggV004JEpWMjBNJE84MyIKICAgICAgICAgfSwKImFs

bG93ZWQiOiB0cnVlCn0KwqAgwqB9LCAidGltZXN0YW1wIjoxNTg0NzAxMDI3NTEwIH0

Get authentication results method

The method allows a relying party to fetch the results of multiple outstanding authentications. It is our recommendation that you generally use the aggregate method, as it is more efficient and reduces network traffic. This is the default behaviour of the client library supplied by Freja eID. 

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

EnvironmentEndpoint
Test
https://services.test.frejaeid.com/authentication/1.0/getResults
Production
https://services.prod.frejaeid.com/authentication/1.0/getResults

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

Parameter nameValue
getAuthResultsRequest
{
   "includePrevious":"Include previously returned results"
}

includePrevious: string, mandatory. Must be 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. 

Example request

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==

Possible errors returned by the method are the following:

Code returnedExplanation
1004You are not allowed to call this method.
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
{
   "authenticationResults":[
      {
         "authRef":"Authentication reference",
         "status":"Authentication status",
         "relyingPartyUserId":"Unique user ID reserved for Relying Parties",
         "details":"JWS signed data, see below",
         "requestedAttributes":{
            "basicUserInfo":{
               "name":"Joe",
               "surname":"Black"
            },
            "emailAddress":"joe.black@verisec.com",
            "allEmailAddresses":[
               {
                  "emailAddress":"joe.black@verisec.com"
               },
               {
                  "emailAddress":"joebl@domain.com"
               }
            ],
            "allPhoneNumbers":[
                {
                    "phoneNumber":"+4600000000"
                },
                {
                    "phoneNumber":"+4611111111"
                }
            ], 
            "dateOfBirth":"1987-10-18",
            "age":"34",
            "photo":"SlBFRyBpbWFnZSBieXRlcyBnb2VzIGhlcmUgLi4u",  
             "addresses":[
               {
                  "country":"SE",
                  "city":"Stockholm",
                  "postCode":"11120",
                  "address1":"c/o Joe Black",
                  "address2":"Visdomsgatan 55",
                  "validFrom":"2020-03-19",
                  "type":"RESIDENTIAL",
                  "sourceType":"GOVERNMENT_REGISTRY"
               },
               {
                  "country":"NO",
                  "city":"Oslo",
                  "postCode":"0001",
                  "address1":"P.O. Box 456",
                  "validFrom":"2020-03-19",
                  "type":"POSTAL",
                  "sourceType":"GOVERNMENT_REGISTRY"
               }
            ],
            "ssn":{
               "ssn":"198710180040",
               "country":"SE"
            },
            "document" : {
               "type":"PASS",
               "country":"SE",
               "serialNumber":"XA0000001",
               "expirationDate":"2027-01-01"
            },
            "documentPhoto":"SlBFRyBpbWFnZSBieXRlcyBnb2VzIGhlcmUgLi4u",
            "registrationLevel":"PLUS",
            "relyingPartyUserId":"94039a98c8d",
            "integratorSpecificUserId":"54059a95c8d",
            "customIdentifier":"vejobla"             
      },
      {
         "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.

Cancel authentication method

This method is used by a relying party to cancel an authentication request. The method is called using HTTP POST through the URLs below:

EnvironmentEndpoint
Test
https://services.test.frejaeid.com/authentication/1.0/cancel
Production
https://services.prod.frejaeid.com/authentication/1.0/cancel

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

Parameter nameValue
cancelAuthRequest
{
   "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.

Example request

If you wish to cancel an authentication request, 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

Possible errors returned by the method are the following:

Code returnedExplanation
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.

Authentication With Different userInfoType

Although we recommend implementing authentication via QR codes and the INFERRED userInfoType, we also support authentication via the following:

  • EMAIL (the user's registered email)
  • PHONE (the user's registered phone number)
  • SSN (the user's social security number)

For more details regarding this implementation, please see this page.