REST API Documentation
Copyright Statement
The specifications and information regarding the product in this manual are subject to change without prior notice. All statements, information, and recommendations in this manual are believed to be accurate but are presented without warranty of any kind, expressed or implied. Users must take full responsibility for their use of any products.
© 2017-2025 Freja eID AB. All rights reserved.
Introduction
Thank you for subscribing to Freja eID services.
Freja eID is an electronic identification (eID) solution for citizens and organisations which can be used for authentication and signing. The essential part of Freja eID service is a smartphone application used for login and signing to all the services that are connected to the user's eID. The second part is a web portal – My Pages – where the user can control how their eID is to be used and has a full record of user history.
In terms of Relying Parties (RPs), Freja eID offers great flexibility in terms of addressing end users.
In instances in which RPs do not need the user's identity verified to a high level of assurance, it is enough to allow users who have only registered with an email in Freja. In Freja we refer to these users as BASIC users.
In instances where a higher degree of identity is required, the user must register with a valid ID document and photo, as well as face enrolment. We refer to these users as EXTENDED and PLUS users.
Users who are EXTENDED and PLUS can then be referred to through their social security number (SSN). In Sweden, this would equate to having established a "personnummer" for the end user. Also, these users can be involved in interactions with web parties that involve login, but also legally binding signatures.
For easier integration, Freja eID also makes a distinction between Relying Parties, depending on the way they can integrate with us:
Stand-alone Relying Party - a Relying Party that wants to integrate with us on their own behalf;
Integrator Relying Party - a Relying Party that usually acts on behalf of their own customers, i.e. other organisations with their own branding, but can also integrate with us on their own behalf;
Integrated Relying Party - a Relying Party which is not connected with Freja eID system directly, rather via the Integrator Relying Party.
Read more about how Integrator and Integrated Relying Parties can integrate with Freja eID in Integrator Relying Party Management.
This document contains instructions for enabling Relying Party applications to use services offered by Freja eID. It is of a technical nature - if you are not a software architect or developer, it is probably the wrong document to read.
Freja eID offers three services to Relying Parties: Authentication Service, Signing Service, and Organisation ID Service. Our recommendation is to read the sections of interest to you in their entirety at least once. On later occasions, use the links to quickly navigate to the section of interest.
Document Versions
Version | Date | Comment |
|---|---|---|
5.25 | 2025-09-11 | Added an additional method to the Organisation ID service. |
5.24 | 2025-04-30 | minRegistrationLevel may now be set to INFERRED. |
5.23 | 2025-02-24 | Added two new attributeToReturn: UNIQUE_PERSONAL_IDENTIFIER and LOA_LEVEL. |
5.22 | 2024-03-04 | Added new method to Organisation ID - Update Organisation ID; added new attributeToReturn: DOCUMENT_PHOTO. |
5.21 | 2023-12-11 | Added new parameter called |
5.20 | 2023-05-10 | Added Custodianship Service with a new method to retrieve user custodianship status. |
5.19 | 2023-02-24 | Added DOCUMENT as attribute to return and requestAttributes parameter in Authentication and Signature Services, as well as Authentication and Signature Services as part of Organisation ID. |
5.18 | 2022-11-09 | Supported XML_MINAMEDDELANDEN advanced signature type. |
5.17 | 2022-10-10 | Supported INFERRED user info type for SIGN transactions. |
5.16 | 2022-09-15 | Supported identifier display types and additional attributes for Organisation ID |
5.15 | 2022-03-11 | Added ORGANISATION_ID as attribute to return and requestAttributes parameter in Authentication and Signature Service. |
5.14 | 2021-12-15 | Added DOCUMENT as attribute to return and requestAttributes parameter in Authentication and Signature Service. |
5.13 | 2021-10-21 | Added PHOTO as attribute to return and requestAttributes parameter in Authentication and Signature Service. |
5.12 | 2021-09-01 | Supported ANY organisation Id issuer when requesting Organisation ID. |
5.11 | 2021-05-27 | Added COVID_CERTIFICATES as attributeToReturn and requestAttributes parameter in Authentication and Signature Service. |
5.10 | 2021-02-22 | Added AGE as attributeToReturn and requestAttributes parameter in Authentication and Signature Service. |
5.9 | 2021-01-26 | Added REGISTRATION_LEVEL as attributeToReturn and requestAttributes parameter in Authentication and Signature Service. |
5.8 | 2020-11-09 | Added ALL_PHONE_NUMBERS to attributeToReturn and requestedAttributes parameter in Authentication and Signature Service. |
5.7 | 2020-08-03 | Introduced new method in the Organisation ID Service - Get all Organisation ID users. |
5.6 | 2020-05-15 | Introduced new JWS certificate for test and production environments. |
5.5 | 2020-04-22 | Added ALL_EMAIL_ADDRESSES to attributeToReturn and requestedAttributes parameter in Authentication and Signature Service. |
5.4 | 2020-04-02 | Added ADDRESSES to attributesToReturn and requestedAttributes parameters in Authentication and Signature Service. |
5.3 | 2020-02-28 | Changed the maximum length of Organisation ID title from 20 to 22 characters and Organisation ID identifier name from 25 to 30 characters. |
5.2 | 2020-02-05 | Changed the maximum length of Organisation ID identifier to 128 characters. |
5.1 | 2019-12-19 | Added INTEGRATOR_SPECIFIC_USER_ID to attributesToReturn and requestedAttributes parameters. This attribute can be requested only by Integrator Relying Parties. |
5.0 | 2019-12-10 | Expanded Organisation ID Service to support initiation of Authentication and Signature requests for a user using the previously added Organisation ID. Adding a custom title of the Organisation ID and the identifier name is now supported. |
4.8 | 2019-11-18 | Introduced a new error code to inform when the userInfo requested in the authentication or signature request does not exist in Freja eID database. |
4.7 | 2019-10-23 | Added Troubleshooting section to Implementation - Troubleshooting and Best Practices. |
4.6 | 2019-10-01 | Included Organisation ID Service. |
4.5 | 2019-01-10 | userInfoType can now be set to INFERRED. Added EMAIL_ADDRESS to attributesToReturn and requestedAttributes parameters in Authentication and Signature responses. |
4.4 | 2018-10-04 | minRegistrationLevel can now be set to EXTENDED. |
4.3 | 2018-09-25 | Added DATE_OF_BIRTH and RELYING_PARTY_USER_ID to attributesToReturn and requestedAttributes parameters in Authentication and Signature responses. Added RP_CANCELED to status string in Authentication and Signature responses. |
4.2 | 2018-07-23 | Added support for PHONE as userInfoType and Extended signature types (see Signature Services). Defined changes to the attributesToReturn parameter for returning attributes BASIC_USER_INFO and SSN in responses. |
4.1 | 2018-06-05 | Added support for returning two more user attributes in the Authentication Services - SSN (personal identity number) and integratorSpecificUserId (a unique user identifier, specific for a particular Integrator RP) |
4.0 | 2018-03-29 | Included Integrator Relying Party Management. Included Custom Identifier Management and updated the support for requesting additional user attributes when initiating the authentication accordingly. Added support for cancelling an authentication or a signing request. Added example requests for all methods in all the services. Updated the custom URL scheme for automatic launch of Freja eID app. |
3.0 | 2018-01-19 | Changed the endpoint URLs for all Authentication Service methods. Adjusted error codes in Authentication Service. Included Signature Service. |
2.6 | 2017-11-01 | Added support for requesting additional user attributes when initiating the authentication. |
2.5 | 2017-09-13 | Changed the JWS header value from x5c to x5t. |
2.4 | 2017-08-10 | Changed the URL for posting the response for identity assertion. |
2.3 | 2017-08-03 | Opaque data must be max128 characters long. Adjusted identity assertion error codes. |
2.2 | 2017-06-30 | Adjusted error codes for validation errors. Instead of generic error 1000 and list of specific errors, specific error is returned directly. |
2.1 | 2017-06-23 | Adjusted error codes to comply with conventions within other services. |
2.0 | 2017-05-29 | Included Authentication Service. Changed examples to use signing certificate under Freja eID TEST root. |
1.0 | 2017-04-26 | This document is a preliminary version. The content of this document is still under review and subject to change. |
Abbreviations
CA | Certificate Authority |
CSR | Certificate Signing Request |
eID | Electronic Identification |
JSON | JavaScript Object Notation |
JWS | JSON Web Signature |
PSKC | Portable Symmetric Key Container |
PKI | Public Key Infrastructure |
REST | Representational State Transfer |
RP | Relying Party |
RSA (cryptosystem) | Rivest–Shamir–Adleman |
SSL/TLS | Secure Sockets Layer/Transport Layer Security |
SSN | Social security number (''personnummer'' in Sweden) |
Getting started
About Freja eID environments
The Freja eID system offers two environments:
Test or Demo Environment, which is designed for testing purposes, it is intended to be used by Relying Parties during the process of integration with Freja eiD to test the integrated services.
Production Environment, which is where the Freja eID services are actually available for business use and where the real-time staging of integrated services is executed.
Note that the Test Environment resembles the Production Environment as much as is possible in all segments.
Before you begin
Test environment checklist
There are several technical requirements that must be in place before the integration with Freja eID can start. Before proceeding, you need to:
Obtain an SSL/TLS client certificate providing you access to the Freja eID Test Environment. For more information, refer to the Certificates section.
Import Freja eID Test root certificate as trusted in the trust store of your application.
Using Freja eID mobile application, register one or more users with the Freja eID Test infrastructure.
Production environment 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 Authentication service.
Provide Freja eID with a logo suitable to represent your organisation in the mobile application, as well as a display name, a URL 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 the maximum length of 100 characters and the description should not exceed 500 characters. The URL can be up to 100 characters long.
Obtain an SSL/TLS client certificate providing you access to the Freja eID Production Environment. For more information, refer to the Certificates section.
Import Freja eID Production root certificate as trusted in the trust store of your application.
Certificates in Freja eID
Freja eID system requires the usage of SSL/TLS certificates for communication with Relying Party applications. The following certificates are used:
Freja eID's server certificate:
Freja eID Test root certificate
Freja eID Production root certificate
Relying Party's client certificate:
Test client certificate
Production client certificate
Additionally, JWS certificates are used to digitally sign the results of authentication and signature requests.
Server SSL certificate
Freja eID Server certificate is used so that Relying Parties can authenticate Freja eID as trusted in their environment. Freja eID's Server certificate should be imported in the trust store of the Relying Party's application. There are two server certificates which you need to use:
Freja eID Test root certificate, when you want to start the integration in the Test Environment
Freja eID Production root certificate, when you want to execute your integration in the Production Environment
Below are Freja eID's Test and Production root certificates, PEM encoded:
Test server root certificate | Production server root certificate |
|---|---|
-----BEGIN CERTIFICATE----- | -----BEGIN CERTIFICATE----- |
Client SSL certificate
As mentioned before, to access and use Freja eID services, you need to obtain a client SSL/TLS certificate. Two client certificates are needed, one for access to the Testing Environment and one for access to the Production Environment. Client certificate authenticates your application when it tries to communicate with Freja eID services. Additionally, Freja eID uses your Client certificate to identify you in its system when you try to send an authentication or signing request.
The following section provides you with instructions on how to generate an SSL/TLS key and a certificate signing request (CSR), which you can then send to Freja eID partner support to provide you with the ready-made client certificate. It also documents how to create a PKCS#12 file.
For this purpose, we used OpenSSL, an open-source cryptography and SSL/TLS toolkit. For more information about OpenSSL, please refer to their official website. Of course, you can use any other CSR generator.
What is an SSL/TLS key and what is it used for?
The SSL/TLS key is a part of the Public Key Infrastructure (PKI) that is generally used in case of SSL/TLS certificates. A Public Key Infrastructure assumes asymmetric encryption, where two types of keys are used: a Private Key and a Public Key (included in an SSL/TLS certificate). The private key is based on the RSA algorithm and is used for authentication and the establishment of an SSL/TLS session. Since encrypted data transmission takes too much time in case of asymmetric encryption, this kind of encryption is only used for a secure exchange of the symmetric key, which is used for actual transmitted data encryption and decryption.
What is a certificate signing request (CSR)?
A certificate signing request (also CSR or certification request) is a block of encoded text that is given to a certificate authority (CA) when applying for an SSL/TLS certificate. It is usually generated on the server where the certificate will be installed on and contains information that will be included in the certificate, such as the organisation name, common name (domain name), locality and country. It also contains the public key that will be included in the certificate. The private key is usually created at the same time as the CSR, thus making a key pair. A CSR is generally encoded using ASN.1, according to the PKCS #10 specification.
Distinguished name
SSL/TLS certificates contain identifying information, such as the qualified domain name used for DNS lookups of your server (also called Common Name), your organisation or company name and location information. This information is called the certificate's Distinguished Name. When generating a CSR on your server, you are asked to enter the Distinguished Name, which uniquely identifies your server.
Below is an example list of required fields for the Subject's Distinguished Name used when generating a CSR request for a Freja eID Relying Party named "ACME AB".
Please note that the fields must be encoded as ASN.1 UTF8String in order to be correctly processed by the Freja eID CA.
DN field | Name | Explanation | Example |
|---|---|---|---|
CN | Common Name | (Optional) Function qualifier, if required. | Document signing service |
OU | Organisational Unit | (Optional) Internal organisational qualifier, if required. | Production |
O | Organisation Name | Legal name of the organisation, as registered with the company register of the country it operates in. | ACME AB |
OID (2.5.4.97) | Organisation identifier | Organisational number, as registered with the company register of the country it operates in. | 556677-8888 |
C | Country | The two-letter ISO abbreviation of the country the company operates in. | SE |
The following characters cannot be used in the Organization Name or the Organizational Unit: < >~ ! @ # $ % ^ * / \ ( ) ?.,&