Security Data (Fraud)

The Security Data API is used to get additional information about a BankID transaction related to preventing fraud.

This method provides data (security data / fraud data) soon after a completed authentication (or signing) that can be used for risk scoring. The tid claim from the ID Token works as the reference to the session.

Only available for select clients

Please not that securityData is currently only available for issuer banks.

Steps

1. The Client redirects the end user to the Authorization Endpoint.
2. The end user completes the BankID authentication or signing process.
3. The Client receives a callback to the callback URL.
4. The Client performs Token exchange and validation to get the Access and ID Tokens.
5. The Client extracts the tid claim from the ID Token.
6. The Client calls the Security Data API with the tid claim to order collection.
7. The Client polls for the Security Data until it is available.

Sequence diagram

sequenceDiagram
    actor u as User
    participant Merchant as Your Web App
    participant BankID as BankID
    participant SecurityData as Security Data API

    u ->> Merchant: Request login
    Note right of Merchant: Client redirects user to BankID
    Merchant->>BankID: GET /authorize?scope=openid&client_id=...
    BankID-->> Merchant: Redirect to callback with code
    Note right of Merchant: Client fetches tokens and verifies
    Merchant->>BankID: POST /token with code
    BankID-->>Merchant: Tokens
    Note right of Merchant: Client requests access token to call Security Data API
    Merchant->>BankID: POST /token with `fraud-data-rs/securityData` scope
    BankID-->>Merchant: Access token
    Note right of Merchant: Client fetches `tid` from original ID Token
    Merchant->>SecurityData: GET /securityData/{tid}
    SecurityData-->>Merchant: Request accepted (202)
    loop Polling
        Merchant->>SecurityData: GET /securityData/{tid}
        SecurityData-->>Merchant: No content (204) or Security Data (200)
    end
    Merchant->>u: Authentication complete

API

Note

You will always find the up-to-date URL for the Security Data API in the OpenID Configuration - as fraud-data-baseurl.

Request

GET [fraud-data-baseurl]/securityData/{tid}

Headers

Authorization: Bearer [access_token]

Response

Accepted (202)

The request has been accepted and the Security Data is being processed.

No content (204)

The Security Data is not yet available. The Client should continue polling.

Warning

The Client should not poll more frequently than once every 5 seconds.

Security Data (200)

The Security Data is available and the response contains the data.

{
  "tid": "754a1771-8f6a-4fa5-b6d7-47d81dda493d",
  "transaction_data": {
    ...
    "BankID_browserName": "Chrome",
    "BankID_timeZone": "Europe/Oslo",
    "BankID_osName": "Linux",
    "BankID_osVersion": "Unknown",
    "BankID_userAgent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/64.0.3282.186 Safari/537.36",
    "BankID_language": "\"en-US\"",
    ...
  },
  "derived_data": {
    ...
    "BankID_User_IP": "195.18.161.2",
    "BankID_Alarm_IDx": "No alarms",
    "BankID_fpf": "0",
    "BankID_fpf_classification": "Unknown",
    "BankID_env": "0",
    "BankID_env_classification": "Unknown",
    "BankID_irs": "0",
    "BankID_irs_classification": "Unknown",
    "BankID_dms": "0",
    "BankID_dms_classification": "Unknown",
    "BankID_ips": "0",
    "BankID_ips_classification": "Unknown",
    ...
  }
}