Foreign ID Document Verification Via Issuer Bank

1 1. Overview
2 2. Purpose and Scope
3 3. Business Flow
4 4. API Endpoint Specification
- 4.1 Endpoint: /check_id
- 4.2 Request
- 4.3 Error Responses
- 4.4 Sample OpenAPI Definition
- 4.5 Authentication:
  - 4.5.1 Example Request Header
  - 4.5.2 Token Validation by Bank

1. Overview

This documentation describes how banks integrate with the BankID backend to verify a non-Norwegian identity document (e.g. passport or national ID card) against a user’s National Identity Number (NNIN) or D-number. The lookup is typically initiated when a customer starts a BAPP activation or requests a password reset in the mobile app. If the bank’s records show that the supplied document and NNIN/D-number match, the BankID backend issues an IdToken; otherwise the process stops and the user is informed that their request cannot proceed.

2. Purpose and Scope

The primary objectives are to:

Support BAPP activation and password resets for users with non-Norwegian ID documents by verifying document + NNIN/D-number combinations.
Ensure that the bank, as the issuer of the BankID certificate, confirms the registration of the NNIN and identity document combination.
If a match is found, then user can proceed further in BAPP activation or password reset, otherwise present an error.

3. Business Flow

Diagram

In-Branch Document Check
- User goes to a bank branch and shows their non-Norwegian ID document (passport or ID card) plus their NNIN/D-number.
- Bank verifies the document and NNIN/D-number, then stores that record in its system.
Starts BAPP activation/Password reset
- User starts BAPP activation/Password reset in the mobile app, enters their NNIN/D-number and scans their ID document.
Backend Verification Request
- App sends the scanned document data and NNIN/D-number to the BankID backend.
- BankID backend first tries to read the NNIN directly from the document; if it can’t, it forwards the data to the issuer bank via the agreed endpoint.
Issuer Bank Lookup
- Issuer Bank checks its customer registry for a matching NNIN/D-number and document record.
- It returns either “verified” (match found) or “match not found.”
Allow or Deny BAPP activation/Password reset
- BankID backend receives the verification result.
- If “verified,” the user can proceed to create their BankID.
- If “match not found,” the app shows an error that registration cannot continue.

4. API Endpoint Specification

Endpoint: `/check_id`

Request

The API must accept a JSON payload with the following details:

Field	Type	Description	Example

Field	Type	Description	Example
`nnin`	string	National Identity Number or D number provided by the user	"12345678901"
`originator`	object	Information about the issuer of the BankID certificate	(See properties below)
`originator.id`	string	BankID issuer ID	"9980"
`document`	object	Details of the identity document provided by the user	(See properties below)
`document.type`	string	Type of document (e.g., passport, ID card)	"passport"
`document.number`	string	The document number	"CCC014356"
`document.issuer`	string	Issuing country code of the document	"AUS"
Authentication	-	API uses Entra ID-based authentication with JWT Bearer token	-
Response Fields	-	-	-
`nnin`	string	National Identity Number or D number from the request	"12345678901"
`timestamp`	string	Date-time of the verification result	"2025-02-10T12:00:00Z"
`matchFound`	boolean	Indicates if the NNIN and document were successfully verified	true / false

Error Responses

Status Code	Description

Status Code	Description
`400 Bad Request`	Invalid input data.
`500 Internal Server Error`	Unexpected server issue.

Sample OpenAPI Definition

openapi: 3.0.1
info:
  title: Check ID document against issuer
  version: 0.0.1
  description: Use ID document as a lookup method to find a user (NNIN or D number)
paths:
  /check_id:
    post:
      summary: Check ID document against issuer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                nnin:
                  type: string
                  description: National Identity Number or D number
                  example: "12345678901"
                originator:
                  type: object
                  description: Issuer of the BankID certificate
                  properties:
                    id:
                      type: string
                      description: BankID issuer ID
                      example: "9980"
                document:
                  type: object
                  description: ID document information
                  properties:
                    type:
                      type: string
                      description: Type of document (e.g., passport, ID card)
                      example: "passport"
                    number:
                      type: string
                      description: ID document number
                      example: "CCC014356"
                    issuer:
                      type: string
                      description: Issuer of the ID document (country code)
                      example: "AUS"
      responses:
        '200':
          description: Lookup completed successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  nnin:
                    type: string
                    description: National Identity Number or D number
                    example: "12345678901"
                  timestamp:
                    type: string
                    format: date-time
                  matchFound:
                    type: boolean
                    description: Indicates if a match was found
                    example: true
        '400':
          description: Bad request
        '500':
          description: Internal server error

Authentication:

The API uses Microsoft Entra ID for authentication. The client application obtains an OAuth 2.0 access token from Entra ID and includes it in the request header as a JWT Bearer token.

Example Request Header

Authorization: Bearer <access_token>
Content-Type: application/json

Token Validation by Bank

The receiving bank's system must validate the access token to ensure it is issued by Entra ID.
The token must be validated against the audience (aud) and the claims role-based access (roles).
If the token is valid, the request should be processed.