Quickstart

Making your first API request.

This page will get you up and running with the Nightfall API so you can start scanning for sensitive data.

Obtain an API key

The Nightfall API requires a valid API key to authenticate your API requests.

You can create API keys in the Dashboard.

Learn more about Authentication and Security.

Make an API Scan Request

Below is an example request to the scan endpoint.

To run this example yourself, replace the API key (NF-rEpLaCe...) with the one you created in the Dashboard.

curl --request POST \
     --url https://api.nightfall.ai/v3/scan \
     --header 'Authorization: Bearer NF-rEpLaCeM3w1ThYoUrNiGhTfAlLKeY123' \
     --header 'Content-Type: application/json' \
     --data '{
       "config": {
            "detectionRules": [
                 {
                      "detectors": [
                           {
                                "detectorType": "NIGHTFALL_DETECTOR",
                                "nightfallDetector": "US_SOCIAL_SECURITY_NUMBER",
                                "minNumFindings": 1,
                                "minConfidence": "LIKELY",
                                "displayName": "US Social Security Number"
                           },
                           {
                                "detectorType": "NIGHTFALL_DETECTOR",
                                "nightfallDetector": "CREDIT_CARD_NUMBER",
                                "minNumFindings": 1,
                                "minConfidence": "LIKELY",
                                "displayName": "Credit Card Number",
                                "redactionConfig": {
                                    "maskConfig": {
                                        "maskingChar": "πŸ‘€",
                                        "charsToIgnore": ["-"]
                                    }
                                }
                           }
                      ],
                      "name": "My Match Rule",
                      "logicalOp": "ANY"
                 }
            ]
       },
       "payload": [
            "The customer social security number is 458-02-6124",
            "No PII in this string",
            "My credit card number is 5310-2768-6832-9293"
       ]
     }'

Detection Rules (detectionRules) indicate what to scan for in your payload.

Detection Rules can be defined two ways: in the Nightfall Dashboard and referenced by UUID, or inline, as shown above.

In this example two of Nightfall's native Detectors are being used: US_SOCIAL_SECURITY_NUMBER and CREDIT_CARD_NUMBER. You can find a full list of native Detectors in the Detector Glossary.

It is also possible to define Detectors inline with your own regular expressions or word list. Additionally, you can extend our native Detectors with exclusion and context rules.

When defining a Detection Rule, you configure the minimum confidence level (minConfidence) and minimum number of times the match must be found (minNumFindings) for the rule to be triggered.

Another feature Nightfall offers is the ability to redact sensitive findings. Detectors may be configured (via redactionConfig) to replace the text that triggered them with a variety of customizable masks, including an encrypted version of the text.

In the payload body, you can see that we are submitting a list of three different strings to scan (payload). The first will trigger the U.S. Social Security Detector. The last will trigger the credit card Detector. The middle example will trigger neither.

Example Nightfall API Scan Response

The Nightfall API returns a response with an array (findings) with a length that corresponds to the length of the payload array. In this example, only the first and last items in the request payload triggered the Detectors, so the second element of the array is empty.

In the first element of the array, you can see details about which Detection Rule was triggered and the data that was found (finding). The response also provides a confidence level (confidence), as well as the location within the original text where the data was found either in terms of bytes (byteRange) or characters (codepointRange).

Nightfall API Response
 
{
  "findings": [
    [
      {
        "finding": "458-02-6124",
        "detector": {
          "name": "US Social Security Number",
          "uuid": "e30d9a87-f6c7-46b9-a8f4-16547901e069"
        },
        "confidence": "VERY_LIKELY",
        "location": {
          "byteRange": {
            "start": 39,
            "end": 50
          },
          "codepointRange": {
            "start": 39,
            "end": 50
          }
        },
        "matchedDetectionRuleUUIDs": [],
        "matchedDetectionRules": [
          "My Match Rule"
        ]
      }
    ],
    [],
    [
      {
        "finding": "5310-2768-6832-9293",
       "redactedFinding": "πŸ‘€πŸ‘€πŸ‘€πŸ‘€-πŸ‘€πŸ‘€πŸ‘€πŸ‘€-πŸ‘€πŸ‘€πŸ‘€πŸ‘€-πŸ‘€πŸ‘€πŸ‘€πŸ‘€",
        "detector": {
          "name": "Credit Card Number",
          "uuid": "74c1815e-c0c3-4df5-8b1e-6cf98864a454"
        },
        "confidence": "VERY_LIKELY",
        "location": {
          "byteRange": {
            "start": 25,
            "end": 44
          },
          "codepointRange": {
            "start": 25,
            "end": 44
          }
        },
        "redactedLocation": {
          "byteRange": {
            "start": 25,
            "end": 44
          },
          "codepointRange": {
            "start": 25,
            "end": 44
          }
        },
        "matchedDetectionRuleUUIDs": [],
        "matchedDetectionRules": [
          "My Match Rule"
        ]
      }
    ]
  ],
  "redactedPayload": [
    "",
    "",
    "My credit card number is πŸ‘€πŸ‘€πŸ‘€πŸ‘€-πŸ‘€πŸ‘€πŸ‘€πŸ‘€-πŸ‘€πŸ‘€πŸ‘€πŸ‘€-πŸ‘€πŸ‘€πŸ‘€πŸ‘€"
  ]
}

Congratulations! You have successfully completed the Nightfall Quickstart.

From here, you can modify the Detectors or payload in your request to get more practice with the Nightfall API.


What’s Next

Learn more about use cases.

For more complex examples, see the following walk throughs: