Nord Security National Identification Number Intelligence API

openapi: 3.2.0
info:
  title: NordStellar Enterprise Data National Identification Number…
  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.'
  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:
    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
    ZeroKnowledgeMultiSample:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/ZeroKnowledgeSample'
    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
    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
    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
    ZeroKnowledgeSaltsSample:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/ZeroKnowledgeSaltSample'
  parameters:
    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
    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
  headers:
    X-Quota-Limit:
      schema:
        type: integer
      description: Quota limit per minute
    X-Quota-Remaining:
      schema:
        type: integer
      description: The number of requests left for the period
  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