Authentication in Organisation ID Service

Initiate authentication method

This method is used by a Relying Party to initiate an authentication request. The method is intended for authentication in online contexts where the access to the Relying Party's service or application is initiated by the end user. The authentications are therefore short-lived — from the point of initiation, the user has a maximum of two minutes to confirm the authentication through a Freja eID mobile application. Only one active authentication may exist for any given end user at any given time. An attempt to concurrently start a second authentication, by the same or a different Relying Party, will cancel both initiated authentication requests.

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

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

You need to have an Organisation ID set for a user to be able to initiate authentication 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
initAuthRequest
{
   "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).

Note: 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)

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

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.

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.
organisationId
"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"}
                                ]
}
Example request with userInfoType set to ORG_ID:

If you wish to initiate authentication request for a user with the specific organisation identifier 'vejobla'  and request their name, surname and SSN, follow these steps:

  1. Create the JSON structure {"userInfoType":"ORG_ID","userInfo":"vejobla", "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=eyJ1c2VySW5mb1R5cGUiOiJPUkdfSUQiLCJ1c2VySW5mbyI6InZlam9ibGEiLC
AiYXR0cmlidXRlc1RvUmV0dXJuIjpbeyJhdHRyaWJ1dGUiOiJCQVNJQ19VU0VSX0lORk8ifSx7ImF0
dHJpYnV0ZSI6IlNTTiJ9XX0=
Example request with userInfoType set to EMAIL:

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
Example request with userIntoType set to PHONE:

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=
Example request with userIntoType set to SSN:

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


Example request with userIntoType set to INFERRED:

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=



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

Methods for retrieving authentication results

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

Get one authentication result method

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

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


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

Parameter name
Value
getOneAuthResultRequest
{
   "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.

Example request:

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


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

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

Note: If userInfoType was set to INFERRED in the initAuthRequest, then userInfoType will be INFERRED and the userInfo will be N/A. We recommend you explicitly ask for attributesToReturn in the initAuth 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.

requestedAttributes

{
   "basicUserInfo":{
      "name":"User's name",
      "surname":"User's surname"
   },
   "emailAddress":"User's 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":"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",
   "customIdentifier":"Custom identifier set by the RP"
}

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

emailAddress: String, representing the user's 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 user's date of birth.

photo: String, Base64 encoded PNG 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.

documentJSON object with information about the user's document used in registration. The 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.

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

organisationIdIdentifier: String, the specific organisation identifier set for the end user. Must be unique within the requesting Relying Party system inside the Freja eID service. 

organisationId: JSON object which contains specific organisation id identifier, map of localised issuer friendly name (EN and SV), organisation code and additional attributes.

relyingPartyUserId: String, 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 Integrator Relying Party Management

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


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@verisec.com",
      "allEmailAddresses":[
         {
            "emailAddress":"joe.black@verisec.com"
         },
         {
            "emailAddress":"joebl@domain.com"
         }
      ],
	"allPhoneNumbers":[
        {
            "phoneNumber":"+4600000000"
        },
        {
            "phoneNumber":"+4611111111"
        }
      ],    
      "dateOfBirth":"1985-11-17",
      "age":"36",
      "photo":"iVBORw0KGgoAAAANSUhEUgAAAhwAAANgCAIAAADoCyYlAAAAAXNSR0IArs4c6QAAAARnQU1BAACx
       jwv8YQUAAAAJcEhZcwAADsMAAA7DAcdvqGQAACAhSURBVHhe7d2xdSJL3sbhm83mQA5KA1chfI48OciRJ+cGgKkk
       CEEJbBb7wWhmEFUNdHW/0EA/5zzOnYWGQmf/P7oaiX/+93//AYAIUQEgRlQAiBEVAGJEBYAYUQEgRlQAiBEVAGJE
       BYAYUQEgRlQAiBEVAGJEBYAYUQEgRlQAiBEVAGJEBYAYUQEgRlQAiBEVAGJEBYAYUQEgRlQAiBEVAGJEBYAYUQEg
       RlQAiBEVAGJEBYAYUQEgRlQAiBEVAGJEBYAYUQEgRlQAiBEVAGJEBYAYUQEgRlQAiBEVAGJEBYAYUQEgRlQAiBEV
       AGJEBYAYUQEgRlQAiBEVAGJEBYAYUQEgRlQAiBEVAGJEBYA...",
       "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"
      },
      "registrationLevel":"EXTENDED"
      "organisationIdIdentifier":"vejobla",
      "organisationId":{
         "identifier":"vejobla",
         "issuerFriendlyName":{
                    "EN":" Freja eID",                          
                    "SV":"FREJA"},
         "issuerCode": null,
         "additionalAttributes":["OrganisationIdAttribute":{
                                  "key":"USER_ID",
                                  "value":"123456789",
                                  "displayText":"ID"}
                                ]
       },
      "relyingPartyUserId":"94039a98c8d",
      "integratorSpecificUserId":"54059a95c8d"
}
Field
Value
Certificate info

See above.

Header

See 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)

eyAiYXV0aFJlZiI6IjEyMzQ1LTY3ODkwLWFiY2RlZiIsICJzdGF0dXMiOiJBUFBST1ZFRCIsICJ1c2VySW5mb1R5cGUiOiJFTUFJTCI
sICJ1c2VySW5mbyI6ImpvZS5ibGFja0B2ZXJpc2VjLmNvbSIsICJyZXF1ZXN0ZWRBdHRyaWJ1dGVzIjp7ICJiYXNpY1VzZXJJbm
ZvIjp7ICJuYW1lIjoiSm9lIiwgInN1cm5hbWUiOiJCbGFjayIgfSwgImVtYWlsQWRkcmVzcyI6ImpvZS5ibGFja0B2ZXJpc2VjLmNvbS
IsICJhbGxFbWFpbEFkZHJlc3NlcyI6WyB7ICJlbWFpbEFkZHJlc3MiOiJqb2UuYmxhY2tAdmVyaXNlYy5jb20iIH0sIHsgImVtYWls
QWRkcmVzcyI6ImpvZWJsQGRvbWFpbi5jb20iIH0gXSwgImFsbFBob25lTnVtYmVycyI6WyB7ICJwaG9uZU51bWJlciI6Iis0NjAw
MDAwMDAwIiB9LCB7ICJwaG9uZU51bWJlciI6Iis0NjExMTExMTExIiB9IF0sICJkYXRlT2ZCaXJ0aCI6IjE5ODUtMTEtMTciLCAiYW
dlIjozNiwgImFkZHJlc3NlcyI6WyB7ICJjb3VudHJ5IjoiU0UiLCAiY2l0eSI6IlN0b2NraG9sbSIsICJwb3N0Q29kZSI6IjExMTIwIiwgIm
FkZHJlc3MxIjoiQy9PIEpvZSBCbGFjayIsICJhZGRyZXNzMiI6IlZpc2RvbXNnYXRhbiA1NSIsICJ2YWxpZEZyb20iOiIyMDIwLTAzLT
E5IiwgInR5cGUiOiJSRVNJREVOVElBTCIsICJzb3VyY2VUeXBlIjoiR09WRVJOTUVOVF9SRUdJU1RSWSIgfSwgeyAiY291bnRyeS
I6Ik5PIiwgImNpdHkiOiJPc2xvIiwgInBvc3RDb2RlIjoiMDAwMSIsICJhZGRyZXNzMSI6IlAuTy4gQm94IDQ1NiIsICJ2YWxpZEZyb2
0iOiIyMDIwLTAzLTE5IiwgInR5cGUiOiJQT1NUQUwiLCAic291cmNlVHlwZSI6IkdPVkVSTk1FTlRfUkVHSVNUUlkiIH0gXSwgInNzb
iI6eyAic3NuIjoiMTk4NTExMTcwMDQwIiwgImNvdW50cnkiOiJTRSIgfSwgInJlZ2lzdHJhdGlvbkxldmVsIjoiUExVUyIsICJyZWx5aW
5nUGFydHlVc2VySWQiOiI5NDAzOWE5OGM4ZCIsICJpbnRlZ3JhdG9yU3BlY2lmaWNVc2VySWQiOiI1NDA1OWE5NWM4ZCIsIC
JjdXN0b21JZGVudGlmaWVyIjoidmVqb2JsYSIsCsKgIMKgIMKgICJjb3ZpZENlcnRpZmljYXRlcyI6ewoidmFjY2luZXMiOiB7CiJjZX
J0aWZpY2F0ZSI6ICJIQzE6TkNGT1hOJVRTTUFITi1IVk44SjdVUU1KNC8zUlpMTTUyWEdQMVdHMkQ1OCpJWEY1OTVUWFIzO
FdBQlJNQjU3Ri84WCpHM005SlVQWTBCWlc0Oi5BNjNITk5WUipHMEM3UEhCTzMzUlcwNUxCUE9GIFFUWUYzNEhHT0lIIDh
MKzZIMVNGKzVGLzNFMUpBRi43NSBKRFhJMDNMOVpJNFE1JUgwQU44Q0owUFpCSVRIUCtQUlJNSlZVTSBJL1BTTSVHQTh
JTSVPJUtJKlcwIC5VUSpOIFJQLStSMllCVjQ0QyRCWEdETzk4OjBMUEhONkQ3TExLKjJIOS04OVVWLTBMLzpJUy1POlM5VVo0
K0ZKRSA0WTNMTC9JSSAwT0M5U1gwKypCODVUJTYyKjVQWkQ1Q0M5VDBIJTpLNVFOWC9HSlpJSTdKU1ROQjk1KzE2TEVU
RjROLlNTLlBLSVhSLlVJQVlVSDJXVlFJMFRIWFpRLko5MSBGSSVCMkxHN1BHJSBCL1VJMllVNU1BWFNHK1czNFBJUUpBWkdB
MjpVRyVVMkU0QVNOTUg4TS00MDVBMU9LLVVLVkNGQjNMQi42REpQSEJTMTVDL0tOS000JElJWCpCMUpTOUFDOTlORTd
QSFRSTysySSo1QzZFQTJVJCA4QzJTVCBJRSVOMSsyNFY3TEQxTFpCQU1BUzMwNldETzEiCn0sCiJ0ZXN0cyI6IHsiY2VydGlm
aWNhdGUiOiJIQzE6TkNGT1hOJVRTTUFITi1IM080OlBWSCBBSjJKJDlKMElJNllKIDQzU0xHL0VCTkcyTjRGQk9NJFY0Ok5RQSB
NOlVDKkdQWFM0TVpLSFpBIEtFN0VDMSAzSzlMVDRENCVLKipJUjFMJTpLRVY0OTlURVc2M1pDRDdMVVoyMzRKVFBWRkhIQ
lk0Ty1PMEcxM0hIMC1LJUlIN1k0L1g4Nk1PQiVSSERNLi1CNi9EMEpBUVRVOEQyJUgwQU44U0owNllCVVNNQUw4Oko1U0g2LU
c5KkU5LiQwNUc5MEYzSFpJNVZBJTNLUVlKWDFKOk5LMkFEVlRBQVpJNjZKIE9LUU1JME9JU1ZCRk9KVlRBMUhBLVhJUkNJI
E9LJUlKNVFCUDdKVTdCSllKKklKNU9JLVlJRTQ2TzkzWE1SOiBLUyROOUhTNS1RSitQQStRSSVLNCRON0JNSStRViVONCtPO
CVNTUcyOUFGNkxGQjgxUU1LUStNTi9RMTlRRThRIFBPRE9GJDZSTlFRM1k3NFhMMS9MSk85VVVNIFFVUS9NTjo0MzU2KkJ
XJCVMKy1KTi5OIExUQldPNTpRTitBMzFVS1hQUk9TTlBTK0RXR0RJOEVIJTJMVUkyTy9FR1lJWVMyR1NTJThTLzQwQVFDSTIif
SwKInJlY292ZXJ5IjogeyAiY2VydGlmaWNhdGUiOiJIQzE6TkNGT1hOJVRTTUFITi1IRk40VFRDNCBTSldLWio5R0JILiBNVTk2NU
hSTFg4M0xRNTVVVFNKVlFPSVZVSzFKWlpQUUEzRFA0T1c2MzFBWDVRTTlJRlkxT1NNTlYxTDhWTkY2QVlNRTBGOk5FM0tV
RDoxM1pNNTo2RUw2RSU2MFQ5MzJRLlJUUkg5L1VQTkY2N0o2UVc2T1ZRT1I2K0c5MC5HLVI1NFcxLlVJMlBIVUlFICQ0WkpK
KiVDTjFUVEI1Qy1PVEYxSiozVEZIMlY0MkYxQ09UJEhGQypJVVo0K0ZKRSA0WTNMTC9JSSAwSEpQN05WREVCMTJKRCoyRD
BISDc4JFpKKkRKV1A0Mlc1OllQSEpVVFJNOE9JOVlPIExFM1VRNU1BMVRIOEwyQ1BJR1NVSFBNVStWQVdPMk84VStWSCpG
WVpRIEg5OTJXICVKTVNHVVZQUVJISVkxKyBIMU8xNlAzKjdVRi5KSjhDN1hCL09JRkQ2NSpWMFdJKjlVVTNFSllSSlg1SDRVNjp
WK1lUR1FGT1BFNlhWViVMVFVLSTdVUEZEQ1FVJEpWRjhDUTo1RThVT0hSJStWL0ZDOSo4IFdNOCRKVjIwTSRPODMiCiAgICA
gICAgIH0sCiJhbGxvd2VkIjogdHJ1ZQp9CsKgIMKgfSwgInRpbWVzdGFtcCI6MTU4NDcwMTAyNzUxMCB9

Get authentication results method

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

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

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


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

Parameter name
Value
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:

Return code
Explanation
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",
            "dateOfBirth":"1987-10-18",
            "age":"36",
            "photo":"iVBORw0KGgoAAAANSUhEUgAAAhwAAANgCAIAAADoCyYlAAAAAXNSR0IArs4c6QAAAARnQU1BAACx
       jwv8YQUAAAAJcEhZcwAADsMAAA7DAcdvqGQAACAhSURBVHhe7d2xdSJL3sbhm83mQA5KA1chfI48OciRJ+cGgKkk
       CEEJbBb7wWhmEFUNdHW/0EA/5zzOnYWGQmf/P7oaiX/+93//AYAIUQEgRlQAiBEVAGJEBYAYUQEgRlQAiBEVAGJE
       BYAYUQEgRlQAiBEVAGJEBYAYUQEgRlQAiBEVAGJEBYAYUQEgRlQAiBEVAGJEBYAYUQEgRlQAiBEVAGJEBYAYUQEg
       RlQAiBEVAGJEBYAYUQEgRlQAiBEVAGJEBYAYUQEgRlQAiBEVAGJEBYAYUQEgRlQAiBEVAGJEBYAYUQEgRlQAiBEV
       AGJEBYAYUQEgRlQAiBEVAGJEBYAYUQEgRlQAiBEVAGJEBYA...",
           "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"
            },
            "registrationLevel":"EXTENDED",
            "organisationIdIdentifier":"vejobla",
            "organisationId":{
              "identifier":"vejobla",
              "issuerFriendlyName":{
                    "EN":" Freja eID",                          
                    "SV":"FREJA"},
              "issuerCode": null,
              "additionalAttributes":["OrganisationIdAttribute":{
                                          "key":"USER_ID",
                                          "value":"123456",
                                          "displayText":"ID"}
                                     ]
            },
            "relyingPartyUserId":"94039a98c8d",
            "integratorSpecificUserId":"54059a95c8d"
      {
         "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 Relying Party 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).

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

requestedAttributes: JSON object (see details as described in the Authentication in Organisation ID Service#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:

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


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

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


Example request:

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


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.