openapi: 3.2.0
info:
  title: NordStellar Enterprise Data National Identification Number Intelligence API
  description: '## Overview

    The NordStellar Enterprise Data API provides comprehensive access to our data breach intelligence platform, enabling organizations to integrate real-time security monitoring and alerting capabilities directly into their existing infrastructure.

    This API allows you to proactively protect your users by detecting when their sensitive information has been compromised in data breaches across the internet.


    **Key Features**:

    - **Real-time Breach Monitoring**: Receive immediate notifications when user data appears in newly discovered data breaches.

    - **Zero-Knowledge Architecture**: Search for compromised sensitive data (credit cards, national identification numbers) using secure hash-based methods that never transmit the actual sensitive information.

    - **Comprehensive Data Sources**: Access intelligence from multiple sources including corporate data breaches, malware infection logs, and stolen credential lists.

    - **Flexible Integration Options**: Support for webhook notifications, bulk operations, and subscription management to fit your organization''s unique requirements.

    - **Enterprise-Grade Security**: Secure authentication methods, rate limiting, and quota management to ensure responsible and controlled API usage.'
  version: '3.1'
servers:
- url: /api/v3/data
security:
- ApiKeyAuth: []
- BasicAuth: []
tags:
- name: National Identification Number Intelligence
  description: 'Endpoints for comprehensive national identification number data monitoring in data breaches, including zero-knowledge search capabilities.

    These operations enable robust national identification number security protection and exposure assessment.'
paths:
  /zero-knowledge/nin/{hash-type}/{hash}:
    get:
      tags:
      - National Identification Number Intelligence
      summary: National identification number search
      description: 'Zero knowledge endpoints are endpoints for sensitive data specifically designed to avoid the transfer of such data.


        The request must include the national identification number product (**SHA-1** or **Argon2id** hash),

        generated using specific secure algorithm.


        Hashed national identification number is returned in a response that start with the filter characters provided in the request,

        together with the list of data categories, that are found in data related to these credit cards.

        Returned data is grouped by **origin** & it''s hex **ID**, where origin is one of the data breach categories (e.g. **databases**, **malware_logs**)

        **Rate limit: 200 per second.**'
      operationId: ninSearch
      parameters:
      - $ref: '#/components/parameters/HashType'
      - $ref: '#/components/parameters/Hash'
      responses:
        '200':
          description: Returns found data
          headers:
            X-RateLimit-Limit:
              schema:
                type: integer
              description: Request limit per second. Defaults 200 per second
            X-RateLimit-Remaining:
              schema:
                type: integer
              description: The number of requests left for the time window.
            X-RateLimit-Reset:
              schema:
                type: string
                format: date-time
            X-Quota-Limit:
              $ref: '#/components/headers/X-Quota-Limit'
            X-Quota-Remaining:
              $ref: '#/components/headers/X-Quota-Remaining'
            X-Quota-Reset:
              $ref: '#/paths/~1email/post/responses/200/headers/X-Quota-Reset'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ZeroKnowledgeSample'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/paths/~1user/get/responses/400/content/application~1json/schema'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/paths/~1user/get/responses/400/content/application~1json/schema'
      security:
      - ApiKeyAuth: []
  /zero-knowledge/nin/{hash-type}/{hash-range}:
    get:
      tags:
      - National Identification Number Intelligence
      summary: National identification numbers search
      description: 'Zero knowledge endpoints are endpoints for sensitive data specifically designed to avoid the transfer of such data.


        The request must include first 5 characters of the national identification number product (**SHA-1** or **Argon2id** hash),

        generated using specific secret and secure algorithm.


        Hashed national identification numbers are returned in a response that start with the filter characters provided in the request,

        together with the list of data categories, that are found in data related to these nationa identification numbers.

        Returned data is grouped by **origin** & it''s hex **ID**, where origin is one of the data breach categories (e.g. **databases**, **malware_logs**)

        **Rate limit: 200 per second.**'
      operationId: ninsSearch
      parameters:
      - $ref: '#/components/parameters/HashType'
      - $ref: '#/components/parameters/HashRange'
      responses:
        '200':
          description: Returns found data
          headers:
            X-RateLimit-Limit:
              schema:
                type: integer
              description: Request limit per second. Defaults 200 per second
            X-RateLimit-Remaining:
              schema:
                type: integer
              description: The number of requests left for the time window.
            X-RateLimit-Reset:
              schema:
                type: string
                format: date-time
            X-Quota-Limit:
              $ref: '#/components/headers/X-Quota-Limit'
            X-Quota-Remaining:
              $ref: '#/components/headers/X-Quota-Remaining'
            X-Quota-Reset:
              $ref: '#/paths/~1email/post/responses/200/headers/X-Quota-Reset'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ZeroKnowledgeMultiSample'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/paths/~1user/get/responses/400/content/application~1json/schema'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/paths/~1user/get/responses/400/content/application~1json/schema'
      security:
      - ApiKeyAuth: []
  /zero-knowledge/nin:
    post:
      tags:
      - National Identification Number Intelligence
      summary: Bulk national identification numbers search
      description: 'Zero knowledge endpoints are endpoints for sensitive data specifically designed to avoid the transfer of such data.


        The request must include a list of first 5 characters of the national identification number products (**SHA-1** or **Argon2id** hash),

        generated using specific secret and secure algorithm.


        Hashed national identification numbers are returned in a response that start with the filter characters provided in the request,

        together with the list of data categories, that are found in data related to these nationa identification numbers.

        Returned data is grouped by **origin** & it''s hex **ID**, where origin is one of the data breach categories (e.g. **databases**, **malware_logs**)

        **Rate limit: 200 per second.**'
      operationId: ninsBulkSearch
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/HashRangesSample'
        required: true
      responses:
        '200':
          description: Returns found data
          headers:
            X-RateLimit-Limit:
              schema:
                type: integer
              description: Request limit per second. Defaults 200 per second
            X-RateLimit-Remaining:
              schema:
                type: integer
              description: The number of requests left for the time window.
            X-RateLimit-Reset:
              schema:
                type: string
                format: date-time
            X-Quota-Limit:
              $ref: '#/components/headers/X-Quota-Limit'
            X-Quota-Remaining:
              $ref: '#/components/headers/X-Quota-Remaining'
            X-Quota-Reset:
              $ref: '#/paths/~1email/post/responses/200/headers/X-Quota-Reset'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ZeroKnowledgeMultiSample'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/paths/~1user/get/responses/400/content/application~1json/schema'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/paths/~1user/get/responses/400/content/application~1json/schema'
      security:
      - ApiKeyAuth: []
  /zero-knowledge/salt/{sha256-prefix}:
    get:
      tags:
      - National Identification Number Intelligence
      summary: Generates a salt based on the provided input data
      description: 'A specific salt is required to successfully use zero knowledge credit card and national identification number lookups.


        To get a salt, hash lookup value (CC or NIN) as SHA256, then use this endpoint and provide first 5 symbols of a lookup value hash.

        **Rate limit: 200 per second.**'
      operationId: salt
      parameters:
      - $ref: '#/components/parameters/HashPrefix'
      responses:
        '200':
          description: Returns a generated salt
          headers:
            X-RateLimit-Limit:
              schema:
                type: integer
              description: Request limit per second. Defaults 200 per second
            X-RateLimit-Remaining:
              schema:
                type: integer
              description: The number of requests left for the time window.
            X-RateLimit-Reset:
              schema:
                type: string
                format: date-time
            X-Quota-Limit:
              $ref: '#/components/headers/X-Quota-Limit'
            X-Quota-Remaining:
              $ref: '#/components/headers/X-Quota-Remaining'
            X-Quota-Reset:
              $ref: '#/paths/~1email/post/responses/200/headers/X-Quota-Reset'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ZeroKnowledgeSaltSample'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/paths/~1user/get/responses/400/content/application~1json/schema'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/paths/~1user/get/responses/400/content/application~1json/schema'
      security:
      - ApiKeyAuth: []
  /zero-knowledge/salt:
    post:
      tags:
      - National Identification Number Intelligence
      summary: Generates many salts based on the provided input data
      description: 'A specific salt is required to successfully use zero knowledge credit card and national identification number lookups.


        To get a salt, hash lookup value (CC or NIN) as SHA256, then use this endpoint and provide first 5 symbols of a lookup value hash.

        **Rate limit: 200 per second.**'
      operationId: salts
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ZeroKnowledgeSaltsEndpoint'
      responses:
        '200':
          description: Returns a generated salt
          headers:
            X-RateLimit-Limit:
              schema:
                type: integer
              description: Request limit per second. Defaults 200 per second
            X-RateLimit-Remaining:
              schema:
                type: integer
              description: The number of requests left for the time window.
            X-RateLimit-Reset:
              schema:
                type: string
                format: date-time
            X-Quota-Limit:
              $ref: '#/components/headers/X-Quota-Limit'
            X-Quota-Remaining:
              $ref: '#/components/headers/X-Quota-Remaining'
            X-Quota-Reset:
              $ref: '#/paths/~1email/post/responses/200/headers/X-Quota-Reset'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ZeroKnowledgeSaltsSample'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/paths/~1user/get/responses/400/content/application~1json/schema'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/paths/~1user/get/responses/400/content/application~1json/schema'
      security:
      - ApiKeyAuth: []
components:
  schemas:
    ZeroKnowledgeSaltsSample:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/ZeroKnowledgeSaltSample'
    ZeroKnowledgeMultiSample:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/ZeroKnowledgeSample'
    HashRangesSample:
      required:
      - hash_ranges
      - hash_type
      type: object
      properties:
        hash_ranges:
          type: array
          description: A list of hash ranges (5 hexadecimal characters) to lookup zero knowledge data
          items:
            type: string
          example:
          - '00000'
          - fffff
        hash_type:
          type: string
          description: "One of the following: **sha1**, **argon2id**.   When using **argon2id**, follow these steps:\n1. **Produce a SHA-256 hash** of the initial value.  \n\n2. **Retrieve the secret salt**  \n   - Take the first 5 characters of the SHA-256 hex string.  \n   - Call the endpoint: **/v3/data/zero-knowledge/salt/{first5}**.  \n   - The endpoint returns JSON containing the salt.\n   - ⚠️ The `salt` field is a **hex-encoded string**.  \n     You must decode it to raw bytes (e.g. `bytes.fromhex(salt)` in Python).  \n     Do **not** use the string value directly as text (`salt.encode(...)`) because it will produce a different final hash.\n\n\n3. **Derive the Argon2id hash** \n   - Input: Initial raw value (not the SHA-256 hash)\n   - Algorithm: **argon2id**  \n   - Parameters:  \n     - Memory: **64 MB (65536 KiB)**  \n     - Iterations: **4**  \n     - Parallelism: **1**  \n     - Key Length: **32 bytes**  \n     - Salt: the raw bytes from step 2  \n   - The output must be the **bare hex-encoded digest** (no Argon2 parameters).  \n\n\n4. **Use the produced hash** to query zero-knowledge endpoints."
          example: argon2id
        limit:
          description: Default is the maximum limit of 500 records
          type: integer
          example: 10
        offset:
          type: integer
          example: 0
    ZeroKnowledgeSample:
      type: object
      properties:
        hash:
          type: string
        data:
          type: array
          description: Contains data grouped by **origin**.
          items:
            type: object
            properties:
              origin:
                type: string
                example: databases
                description: Contains data origin (either **databases** or **malware_logs**)
              data:
                type: array
                description: Contains origin items with leaked data keys.
                items:
                  type: object
                  properties:
                    id:
                      type: string
                      description: Origin record id.
                      example: 66c4d3912b183418f7743576
                    compromised_data:
                      type: array
                      description: Compromised data keys
                      items:
                        type: string
                      example:
                      - password
                      - nin
                      - surname
    ZeroKnowledgeSaltsEndpoint:
      required:
      - sha256_prefixes
      type: object
      properties:
        sha256_prefixes:
          type: array
          description: A list of first 5 symbols of SHA256 hashes of the lookup values
          items:
            type: string
          example:
          - '00000'
          - fffff
    ZeroKnowledgeSaltSample:
      type: object
      properties:
        sha256_prefix:
          type: string
          example: 915af
          description: Corresponding input for generated salt
        salt:
          type: string
          description: Zero knowledge lookup salt, calculated using request input
          example: 0e4f4b0e81bad42097299d18869f8d7f
  headers:
    X-Quota-Remaining:
      schema:
        type: integer
      description: The number of requests left for the period
    X-Quota-Limit:
      schema:
        type: integer
      description: Quota limit per minute
  parameters:
    HashPrefix:
      name: sha256-prefix
      in: path
      required: true
      description: First 5 symbols of SHA256 hash of the lookup value
      schema:
        type: string
    HashRange:
      name: hash-range
      in: path
      required: true
      schema:
        type: string
    Hash:
      name: hash
      in: path
      required: true
      schema:
        type: string
    HashType:
      name: hash-type
      in: path
      required: true
      description: "One of the following: **sha1**, **argon2id**.   When using **argon2id**, follow these steps:\n1. **Produce a SHA-256 hash** of the initial value.  \n\n2. **Retrieve the secret salt**  \n   - Take the first 5 characters of the SHA-256 hex string.  \n   - Call the endpoint: **/v3/data/zero-knowledge/salt/{first5}**.  \n   - The endpoint returns JSON containing the salt.\n   - ⚠️ The `salt` field is a **hex-encoded string**.  \n     You must decode it to raw bytes (e.g. `bytes.fromhex(salt)` in Python).  \n     Do **not** use the string value directly as text (`salt.encode(...)`) because it will produce a different final hash.\n\n\n3. **Derive the Argon2id hash** \n   - Input: Initial raw value (not the SHA-256 hash)\n   - Algorithm: **argon2id**  \n   - Parameters:  \n     - Memory: **64 MB (65536 KiB)**  \n     - Iterations: **4**  \n     - Parallelism: **1**  \n     - Key Length: **32 bytes**  \n     - Salt: the raw bytes from step 2  \n   - The output must be the **bare hex-encoded digest** (no Argon2 parameters).  \n\n\n4. **Use the produced hash** to query zero-knowledge endpoints.  "
      schema:
        type: string
  securitySchemes:
    BasicAuth:
      type: http
      scheme: basic
      description: Authorization string. Needs to be in the standard BasicAuth format - "Basic BASE64_CREDENTIALS", where BASE64_CREDENTIALS is the user username:password encoded in base64 format.
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-KEY