# eID – Sweden --- ## Overview --- Freja eID is a mobile electronic identity (eID) issued and operated by Freja eID Group AB. It is approved by the Swedish Agency for Digital Government (DIGG) and can be used to authenticate users for hundreds of public and private e-services in Sweden and beyond. Unlike many other Swedish eID schemes, Freja can be issued both to Swedish citizens with a _personnummer_ and to foreign citizens based on biometric passports, and it supports users in 160+ countries via a Universal Personal Identifier (UPI). Through ZignSec, Freja eID is exposed as a standardized identity verification product that you can use for: - **Identification** – Strong customer authentication and user login. - **Digital Onboarding** – KYC/identity verification as part of customer onboarding flows. ZignSec’s Freja integration is built on the **Identity Verification** session APIs and supports multiple ways of identifying the end user: - Social security number (SSN / national ID) - QR code - Phone number - Email address --- ## Identification ### Authentication with Freja eID Freja eID supports different **registration levels** (Basic, Extended, Plus), which map to different levels of assurance (LoA1–LoA3). Within ZignSec, you can choose: - Which registration level is required (for example `BASIC`, `EXTENDED`, or `PLUS`). - Which attributes to return (for example basic user info, email, addresses, SSN, etc.). - How the user is identified (SSN, QR code, phone, or email). Freja is particularly useful as: - A **primary Swedish eID** for users who prefer Freja eID over BankID. - A **fallback** or complementary method when users cannot use BankID (for example foreign citizens or users without a Swedish bank relationship). #### Levels of assurance supported Freja supports three product / registration levels: - **BASIC** – Lower assurance; suitable for simple login or low-risk use cases. - **EXTENDED** – Medium assurance; user has registered an ID document. - **PLUS** – Highest level of assurance (government-approved LoA3 for private persons). You typically map them as: - **BASIC (LoA1)** - Simple account access with limited risk. - When you only need **email** and basic profile information. - **EXTENDED (LoA2-ish)** - When document-based verification is needed but risk is moderate. - Good for many private services that need verified identity and contact details. - **PLUS (LoA3)** - When your service is regulated or requires **strong, government-approved identity assurance**. - For example: public sector services, financial services, higher-risk KYC flows, or where you must rely on an identity at LoA3. > [!NOTE] > This is a general guideline. You are responsible for your own risk assessment and for selecting a registration level and attribute set that matches your legal and business requirements. ### Security Freja eID+ is approved at **Trust Level 3 (LoA3)** according to the Swedish DIGG trust framework, and Freja OrgID is similarly approved for employee e-IDs. Key points: - All traffic between ZignSec and Freja is over TLS, using strong cipher suites (see ZignSec [[Introduction]] for environment-level security details). - Authentication requires the user’s **PIN** and optionally biometric verification (fingerprint / Face ID), handled inside the Freja mobile app. - When used for international users, Freja relies on **biometric passports** and a persistent UPI instead of national ID numbers. ### End User Data returned The exact attributes depend on your configuration (`attributes_to_return`, minimum registration level, and what data the user has in Freja). Typical data that can be returned via ZignSec’s Freja integration includes: - **Personal details** - Full name (given + family name) - Date of birth - Age - Gender (if configured) - **Identifiers** - National identity number / SSN (if allowed and requested) - Issuing country for SSN - Freja registration level (Basic / Extended / Plus) - Freja relying-party user ID - Freja integrator-specific user ID - UPI / other Freja-specific identifiers (for international users) - **Contact data** - Primary email address - All email addresses - All phone numbers - **Address data** - Main address (country, city, postal code, street) - All registered addresses - **Document & verification data** (for higher levels) - Document type (passport, ID card, etc.) - Document serial number and expiry date - Derived document data (e.g. FrejaDocumentData) - **Derived / formatted values** - Formatted full address - Parsed address components The set of attributes you receive is fully controlled by: - The **`attributes_to_return`** list in your session request. - The **`min_registration_level`** you require. - What information is available in the user’s Freja profile. ### Scopes / attributes configuration On the ZignSec side, Freja’s attribute model is exposed via standard `metadata` fields on the session: - `attributes_to_return` – a list like: `["BASIC_USER_INFO", "EMAIL_ADDRESS", "ALL_EMAIL_ADDRESSES", "ALL_PHONE_NUMBERS", "DATE_OF_BIRTH", "AGE", "PHOTO", "ADDRESSES", "SSN", "REGISTRATION_LEVEL", "RELYING_PARTY_USER_ID", "INTEGRATOR_SPECIFIC_USER_ID", "CUSTOM_IDENTIFIER"]` - `min_registration_level` – one of `BASIC`, `EXTENDED`, `PLUS`. - `user_info` – how the user is identified (SSN details, phone number, or email). For the full attribute list and mapping to OIDC claims, see the Freja and Sweden OIDC attribute specifications. ### User Experience Guidelines for Freja Integration #### Identity providers & methods Freja offers several ways for the user to authenticate: 1. **Freja by SSN** - User is identified by their national ID / SSN (SE, NO, FI, DK are supported in the current ZignSec configuration). - Freja validates the person against its register. 2. **Freja by QR code** - User scans a QR code in the browser using the Freja app. - Very convenient for desktop→mobile flows. 3. **Freja by phone number** - User is looked up and authenticates based on their registered phone number. 4. **Freja by email** - User is identified and authenticates using their email address, useful for simple onboarding flows. #### Basic flow: End-user interactions Typical Freja login / verification via ZignSec consists of: 1. **Start session in your backend** - You call ZignSec’s Freja endpoint (SSN / QR / phone / email) with: - `attributes_to_return` - `min_registration_level` - `redirect_success` / `redirect_failure` - Optional `webhook` and `relay_state` 2. **User interaction in Freja** - User receives a push, scans a QR, or opens Freja based on your chosen method. - User reviews the requested action and attributes. - User authenticates with PIN and, if enabled, biometrics. 3. **Result** - Freja returns the result to ZignSec. - ZignSec updates the session and: - Redirects the user back to your `redirect_success` / `redirect_failure` URL. - Sends webhooks if configured. - Your system fetches the result via the session or Session Data API. #### Customization Freja’s UI is controlled primarily inside the Freja app, but you can customize the **surrounding UX**: - The wording and design of the **“Log in with Freja eID”** or **“Verify with Freja eID”** call-to-action. - Whether you show **QR flows** prominently on desktop. - How you communicate: - Required registration level (e.g. “Freja eID+ required”) - Which data will be retrieved (e.g. SSN, address, etc.). > [!NOTE] > Make sure your privacy policy and consent wording clearly describe which attributes you obtain from Freja and how you will use them. --- ## Digital onboarding ### Using Freja in the onboarding process ZignSec’s Freja integration can be part of a **full KYC onboarding flow**: - Start an **Identity Verification** session with Freja as eID. - Retrieve verified identity data (name, date of birth, SSN or UPI, address, etc.). - Optionally combine with: - ID & Biometric verification - PEP & Sanction checks - Business register checks (for KYB) Freja is especially valuable for: - Onboarding **foreign citizens** who do not yet have a Swedish _personnummer_ (via UPI and passport-based registration). - Onboarding Swedish residents for services that require LoA3 or strong identity proof. ### Storing SSN / UPI from end users If you plan to **store SSNs** or other strong identifiers (like UPI) obtained via Freja: - You must have a **legal basis** (e.g. KYC/AML obligations). - You must handle **consent and transparency** yourself in line with GDPR and local regulations. - You are responsible for retention, minimization, and access control. ZignSec simply relays attributes obtained from the Freja identity provider according to your configuration. > [!NOTE] > National identity numbers and UPI are considered **sensitive identifiers**. Make sure your legal, compliance, and security teams approve how you store and process them. ### Error Handling #### Handling user cancellation The end user can cancel a Freja authentication / verification at any time: - In that case: - The Freja app cancels the request. - ZignSec updates the Freja session. - The user is redirected to `redirect_failure` (or a generic error page if not configured). - A webhook can be sent with a “cancelled” status if you configured a webhook URL. Your application should: - Detect cancelled sessions (for example by checking status in the result). - Offer the user a way to: - Retry with Freja, or - Choose another identity method (e.g. BankID). #### Handling errors If an error occurs during a Freja session, typical scenarios are: 1. The Freja app shows an error and the user can retry or abort. 2. The user is redirected back to your `redirect_failure` URL. 3. The Session Data result includes an error status / code that you can log and map to your own error handling. 4. In rare cases (network issues, app problems), the user may not be redirected; you should implement **timeouts and polling** on the session to detect stale or failed flows. Use the general ZignSec [Error Handling](https://chatgpt.com/g/g-p-68b81746a91c8191947d2a1047b814e9-documentation/guides/Error%20handling.md) guidelines for HTTP-level and platform-level errors. --- ## API Overview ### Core Functionalities #### Environments Freja uses the **Identity Verification** session APIs hosted on ZignSec’s gateway. For Freja specifically, you will use: - **Test Environment** - `https://test-gateway.zignsec.com/core/api/sessions/identity_verification/…` - **Production Environment** - `https://gateway.zignsec.com/core/api/sessions/identity_verification/…` Each Freja flow has its own path segment, for example `freja_id_ssn`, `freja_id_qr`, etc. (see API Endpoints below). > For production, use the same paths as in TEST but replace > `https://test-gateway.zignsec.com` with `https://gateway.zignsec.com`. #### Authentication Each request to ZignSec’s API must include your **subscription key** in the `Authorization` header. - Keys are issued per environment (TEST / PROD) by ZignSec support. - We recommend rotating keys regularly via a support request (or via automation if available). - If you need different configurations, you can have **multiple tenants** and API keys. ### REST API #### Headers |Header|Description|Required| |---|---|---| |Authorization|Subscription key issued by ZignSec, for example: `Authorization: 123456add0cff22873c428e987654321`|Yes| |Content-Type|Media type of the request body. Use `application/json` when sending JSON payloads.|Yes| #### API – Documentation - **Freja product documentation (detailed v5 flow):** `https://docs.zignsec.com/eids/v5-freja-id/` - **Swagger UI – TEST (Freja ID Sweden group):** `https://test-gateway.zignsec.com/#/eIDs%20-%20Freja%20ID%20Sweden/` - **Swagger UI – PROD (Freja ID Sweden group):** `https://gateway.zignsec.com/#/eIDs%20-%20Freja%20ID%20Sweden/` Use the Swagger UI to: - Inspect all request/response schemas. - Try the Freja endpoints directly against TEST. - Generate client code from the OpenAPI definition (via your preferred tooling). #### API Endpoints All Freja endpoints below are **POST** session-creation calls, plus a shared **GET session** endpoint for fetching the result. > Base host is either `https://test-gateway.zignsec.com` (TEST) or > `https://gateway.zignsec.com` (PROD). Only the host changes between environments. ##### Identification ###### Identity Verification with Freja ID (SSN) **Endpoint (relative path):** `POST /core/api/sessions/identity_verification/freja_id_ssn` **Description:** Start a Freja identity verification using **national identity number / SSN** as the user identifier. Supports `country` values `SE`, `NO`, `FI`, `DK`, with specific formatting rules per country (for example 12-digit Swedish _personnummer_ without separators). Use this when: - You already know the user’s SSN, and - You want Freja to strongly verify that the user controls that identity. ###### Identity Verification with Freja ID (QR) **Endpoint (relative path):** `POST /core/api/sessions/identity_verification/freja_id_qr` **Description:** Creates a Freja verification session that returns a **base64-encoded PNG QR code**. The user scans this QR code with the Freja app (commonly on a separate device) and then authenticates. Use this when: - The user is on a desktop or kiosk. - You want a seamless “scan & approve in app” experience. ###### Identity Verification with Freja ID (Phone) **Endpoint (relative path):** `POST /core/api/sessions/identity_verification/freja_id_phone` **Description:** Starts a Freja session using the user’s **phone number** as the identifier. Freja will resolve the user and send the authentication request to the correct mobile device. Use this when: - You do not have SSN but do have a phone number that is registered in Freja. - You want a “log in with phone number” UX. ###### Identity Verification with Freja ID (Email) **Endpoint (relative path):** `POST /core/api/sessions/identity_verification/freja_id_email` **Description:** Starts a Freja session using the user’s **email address** as the identifier. Use this when: - You only have the user’s email address. - You want a **lightweight identification / login** mechanism, possibly combined with a requirement for higher registration levels. ##### Get session details Freja verification results are retrieved through ZignSec’s **Session Data** API. - **Endpoint:** `GET /core/api/sessions/{sessionId}` _(or via the “Session Data / getSessionById” operation in Swagger UI)_ - **Swagger (TEST group):** `https://test-gateway.zignsec.com/#/Session%20Data/getSessionById` **Description:** - Returns: - Session status (e.g. pending, success, failure, cancelled). - Result payload including Freja attributes according to your configuration. - Any error codes / messages (when applicable). - Works for **all** Freja entry methods (SSN, QR, phone, email). > [!NOTE] > Session settings (like attributes, registration level, callback URLs) can be changed per request. If you need custom defaults or advanced flows, contact ZignSec support. --- ## Testing ZignSec does not distribute fixed shared Freja test users. Instead, you use Freja’s **official test mode** and create your own test accounts in the Freja app. Freja provides detailed “Testing Instructions” for relying parties, including how to: - Put the Freja app into **test mode** (orange header). - Perform **Basic registration** (email + PIN). - Add and verify **ID documents**. - Upgrade to **Freja eID Plus** in test. - Use the **Test Vetting Portal** to promote test accounts. Recommended steps: 1. **Enable test mode in the Freja app** following Freja’s documentation. 2. Register one or more **test identities** (with or without SSN) at the level(s) you need (Basic, Extended, Plus). 3. Use ZignSec TEST endpoints: - `https://test-gateway.zignsec.com/core/api/sessions/identity_verification/freja_id_ssn` - `https://test-gateway.zignsec.com/core/api/sessions/identity_verification/freja_id_qr` - `https://test-gateway.zignsec.com/core/api/sessions/identity_verification/freja_id_phone` - `https://test-gateway.zignsec.com/core/api/sessions/identity_verification/freja_id_email` 4. Complete the Freja flows on your device and verify that: - Redirects (`redirect_success` / `redirect_failure`) work as expected. - Webhooks (if configured) are received and parsed correctly. - `GET /core/api/sessions/{sessionId}` returns the expected attributes and statuses. For more details, refer to **Freja eID Relying Party Documentation – Testing instructions** on the Freja site and to ZignSec’s **v5 – Freja ID -se** product page for up-to-date examples.