This page:

Other services

Management:

Best practices:

Overview

The Freja eID Organisation ID service allows Relying Parties to set a particular identifier to any user. The end user will have previously downloaded the Freja eID mobile application on one or more iOS or Android devices they possess, and registered an account in Freja eID, allowing Relying Parties to refer to them through the use of one or more usernames.

The Organisation ID service is available to end users that have Freja eID Extended (users whose identity has been validated with an ID document) or Plus (users who, in addition to Extended, have had a physical meeting as a further measure of security; this level is only available in Sweden.)

Before you begin

Disclaimer

We retain the right to extend the API with new optional parameters, new response fields and error codes. Within the same API version, these additions shall be made strictly without altering existing response fields and error codes so as not to compromise your system's stability. Your application therefore MUST be able to handle unknown response fields and error codes. In the case of unknown response fields, the application SHOULD ignore them and process only those it understands. In the case of unknown error codes, the application MUST present a generic error message to the end-user.

There are several technical requirements that must be in place before the implementation can start. Please complete the checklist below before proceeding:

  • Obtain an SSL client certificate providing you access to the Freja eID test environment.
  • Import Freja eID Test root certificate as trusted into the trust store of your application.
  • Using Freja eID mobile application, register one or more users with the Freja eID Test infrastructure.

Production checklist

In order to use Freja eID in a production environment, you must fulfil the following:

  • Sign a contract allowing your organisation to access the production Freja eID Organisation ID service.
  • Provide Freja eID with a logo suitable to represent your organisation in the mobile application, as well as a display name and a short description. Please note that:
    • The logo must be delivered in one of the vector file formats: AI (Adobe Illustrator Artwork), EPS (Encapsulated PostScript) or editable PDF (Portable Document Format). The preferable format is AI (filename extension is .ai).
    • The display name is restricted to maximum length of 20 characters and the description should not exceed 75 characters. The URL can be up to 100 characters long.
  • Obtain an SSL client certificate providing you access to the Freja eID production environment.
  • Import Freja eID Production root certificate as trusted into the trust store of your application.

Initiate Add Organisation ID method

This method is used by a Relying Party to initiate a transaction for setting an Organisation ID identifier to a user. The identifier must be unique within the Relying Party's system. If the Organisation ID identifier is set for a user multiple times, this identifier will be overridden and the last one will be active.

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

System
Method endpoints
Test
https://services.test.frejaeid.com/user/manage/1.0/organisationId/initAdd
Production
https://services.prod.frejaeid.com/user/manage/1.0/organisationId/initAdd

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

Parameter name
Value
initAddOrganisationIdRequest
{
   	"userInfoType":"User info type",
   	"userInfo":"User information corresponding to user info type",
   	"minRegistrationLevel":"Minimum required registration level of a user",
   	"expiry":"Expiry time for the request",
   	"identifier":"Organisation ID identifier",
}

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

Note: Currently, CUST is not supported.

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.

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)

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

custuserinfo

Reserved for future use, not supported in current version of Freja eID.

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

expiry: long, optional. Describes the time until which the relying party is ready to wait for the user to confirm the add organisation eID request. Expressed in milliseconds since January 1, 1970, 00:00 UTC. Minimum value is current time +2 minutes, maximum value is current time +30 days. If not present, defaults to current time +7 days.

identifier: string, mandatory, 25 characters maximum. The custom attribute to be set for the end user. Must be unique within the requesting relying party system inside the Freja eID service.

Example request with userInfoType set to EMAIL:

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

  1. Create the JSON structure {"userInfoType":"EMAIL","userInfo":"joe.black@verisec.com","minRegistrationLevel":"EXTENDED","expiry":1517526000000,"identifier":"vejodoe"}
  2. Encode the JSON structure to Base64.
  3. Create the HTTP POST request with a POST parameter name initAddOrganisationIdRequest 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):

initAddOrganisationIdRequest=eyJ1c2VySW5mb1R5cGUiOiJFTUFJTCIsInVzZXJJbmZvIjoiam9lLmJsYWNrQHZlcmlzZWMuY29tIiwibWl
uUmVnaXN0cmF0aW9uTGV2ZWwiOiJFWFRFTkRFRCIsImV4cGlyeSI6MTUxNzUyNjAwMDAwMCwiaWRlbnRpZmllciI6InZlam9kb2UifQ==
Example request with userIntoType set to PHONE:

If you wish to initiate an 'Add Organisation ID' request for a user with a phone number '+46731234567':

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

The HTTP body should be the following:

initAddOrganisationIdRequest=eyJ1c2VySW5mb1R5cGUiOiJQSE9ORSIsInVzZXJJbmZvIjoiKzQ2NzMxMjM0NTY3IiwibWluUmVnaXN0cmF0
aW9uTGV2ZWwiOiJFWFRFTkRFRCIsImV4cGlyeSI6MTUxNzUyNjAwMDAwMCwiaWRlbnRpZmllciI6InZlam9kb2UifQ==
Example request with userIntoType set to SSN:

If you wish to initiate an 'Add Organisation ID' 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":"EXTENDED","expiry":1517526000000,"identifier":"vejodoe"}
  4. Encode the JSON structure to Base64.
  5. Create the HTTP POST request with a POST parameter name initAddOrganisationIdRequest and the Base64 encoded JSON structure from the step 4 as its value.

The HTTP body should be the following:

initAddOrganisationIdRequest=eyJ1c2VySW5mb1R5cGUiOiJTU04iLCJ1c2VySW5mbyI6ImV5SmpiM1Z1ZEhKNUlqb2lVMFVpTENKemMyNGlPa
Ul4T1RnNU1EVXlNVGd3TnpJaWZRPT0iLCJtaW5SZWdpc3RyYXRpb25MZXZlbCI6IkVYVEVOREVEIiwiZXhwaXJ5IjoxNTE3NTI2MDAwMDAwLCJpZGV
udGlmaWVyIjoidmVqb2RvZSJ9



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.
1005The user has not enabled your service.
1007Invalid min registration level.
1008Unknown Relying Party.
1010JSON request cannot be parsed.
4000Invalid or missing identifier.
4001There is no user for given identifier.
4002This organisation id identifier is already used.
4003Invalid expiry.


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
{ 
   	"orgIdRef":"Reference to be submitted in getOneResult method"
}

orgIdRef: string, mandatory. A reference unique to the transaction, that can be used to query the result of a specific transaction for adding Organisation ID(see Get One Organisation ID Result method below).

 

Get One Organisation ID Result method

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

System
Method endpoint
Test
https://services.test.frejaeid.com/user/manage/1.0/organisationId/getOneResult
Production
https://services.prod.frejaeid.com/user/manage/1.0/organisationId/getOneResult


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

Parameter name
Value
getOneOrganisationIdResultRequest
{
   	"orgIdRef":"Organisation ID reference"
}

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

Example request:

If you wish to fetch an Organisation ID result with the reference previously returned from a call to initAddOrganisationIdRequest (for a user with an email address: joe.black@verisec.com), follow these steps:

  1. Create the JSON structure {"orgIdRef":"TrLA9zdxCBlNOQNvkdhAM14mJmlL20digC7+QgEVRwmE7SH8Qm0swWIc6whfKm4Y"}
  2. Encode the JSON structure to Base64.
  3. Create the HTTP POST request with a POST parameter name getOneOrganisationIdResultRequest 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):

getOneOrganisationIdResultRequest=eyJvcmdJZFJlZiI6IlRyTEE5emR4Q0JsTk9RTnZrZGhBTTE0bUptbEwyMGRpZ0M3K1FnRVZSd21FN1NIOFFtMHN3V0ljNndoZkttNFkifQ==


Possible errors returned by the method are the following:

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


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


JSON Response Value in body
Response body
{
   	"orgIdRef":"Organisation ID reference",
   	"status":"Status of Organisation ID transaction",
   	"details":"signed data, see below"
}

orgIdRef: string, mandatory . The reference of the Add Organisation ID request.

status: string, mandatory. One of: STARTED (the transaction has been started but not yet delivered to the user's Freja eID application), DELIVERED_TO_MOBILE (the Freja eID app has received the transaction), OPENED (the user has opened and seen the 'Add Organisation ID' request but has neither cancelled nor approved it yet), CANCELED (the end user declined the 'Add Organisation ID' request), RP_CANCELED (the 'Add Organisaiton ID' request was sent to the user but cancelled by the RP before the user could respond), EXPIRED (the 'Add Organisation ID' request was not approved by the user within the set time frame), APPROVED (the end user has approved the 'Add Organisation ID' request).

Note: In the current version of Freja eID, OPENED status is not supported.

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

details

The content of this response element will contain a JWS in compact serialised form as following:

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


JWS Protected Header

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

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


JWS Payload

{
	"orgIdRef":"Organisation ID reference",
   	"status":"Status of Organisation ID transaction",
   	"userInfoType":"User info type",
   	"userInfo":"User information corresponding to user info type",
   	"minRegistrationLevel":"Minimum required registration level of a user",
   	"timestamp":"Time when transaction was approved by end user",
   	"signatureType":"Signature type",
   	"signatureData":{
    	"userSignature":"The signature produced by the end user",
      	"certificateStatus":"Evidence of end-users certificate status"
   }
}

orgIdRef: See orgIdRef above.

status: See status above.

userInfoType: See userInfoType as described in Initiate Add Organisation ID method.

userInfo: See userInfo as described in Initiate Add Organisation ID method.

minRegistrationLevel: See registrationLevel as described in Initiate Add Organisation ID method.

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

signatureType: string, mandatory. For the Organisation ID service, this field has value SIMPLE. See signatureType as described in Signature Services.

signatureData: see fields below, mandatory.

userSignature: the produced signature, string, mandatory. Contains the user's signature in the requested format. The user's signature will implicitly contain the signed text which will contain Organisation ID identifier set to the user.

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

  

Cancel Add Organisation ID method

This method is used by a Relying Party to cancel an 'Add Organisation ID' request.

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

System
Method endpoints
Test
https://services.test.frejaeid.com/user/manage/1.0/organisationId/cancel
Production
https://services.prod.frejaeid.com/user/manage/1.0/organisationId/cancel


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

Parameter name
Value
cancelAddOrganisationIdRequest
{
   	"orgIdRef":"Organisation ID reference"
}

orgIdRef: string, mandatory. The value must be equal to an Organsation iD reference previously returned from a call to the Initiate Add Organisation ID method.

Example request:

If you wish to cancel an Add Organisation ID request, follow these steps:

  1. Create the JSON structure {"orgIdRef":"TrLA9zdxCBlNOQNvkdhAM14mJmlL20digC7+QgEVRwmE7SH8Qm0swWIc6whfKm4Y"}
  2. Encode the JSON structure to Base64.
  3. Create the HTTP POST request with a POST parameter name cancelAddOrganisationIdRequest 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):

cancelAddOrganisationIdRequest=eyJvcmdJZFJlZiI6IlRyTEE5emR4Q0JsTk9RTnZrZGhBTTE0bUptbEwyMGRpZ0M3K1FnRVZSd21FN1NIOFFtMHN3V0ljNndoZkttNFkifQ==


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.

Delete Organisation ID method

This method is used by a Relying Party to delete an Organisation ID identifier from a user.

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

SystemMethod endpoints
Test
https://services.test.frejaeid.com/user/manage/1.0/organisationId/delete
Production
https://services.prod.frejaeid.com/user/manage/1.0/organisationId/delete

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

Parameter nameValue
deleteOrganisationIdRequest
{
   	"identifier":"Organisation ID identifier"
}

identifier: string, mandatory, 25 characters maximum. The custom attribute to be deleted.

Example request

If you wish to delete an Organisation ID identifier from a user, follow these steps:

  1. Create the JSON structure {"identifier":"vejodoe"}
  2. Encode the JSON structure to Base64.
  3. Create the HTTP POST request with a POST parameter name deleteOrganisationIdRequest 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):

deleteOrganisationIdRequest=eyJpZGVudGlmaWVyIjoidmVqb2RvZSJ9

Possible errors returned by the method are the following:

Return codeExplanation
1008Unknown relying party.
4000Invalid or missing identifier.
4001There is no user for given identifier.