> ## Documentation Index
> Fetch the complete documentation index at: https://docs.encrata.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Exposed API Keys

> Scan collected text for exposed credentials and check whether supported credentials are still live.

Exposed API Keys scans text you already collected for API keys, tokens, and other credentials.

`POST /api/lookup/breaches/exposed-keys`

Requires an [Encrata API key](/authentication) in the `Authorization` header.

## Request

<ParamField body="content" type="string" required>
  The text to scan. Send a crawled page, paste, message, or dump. The maximum
  size is 256 KB per request.
</ParamField>

<ParamField body="type" type="integer" default="0">
  Detection profile: `0` uses the standard engine, `1` uses the alternate
  engine, and `2` runs both and merges duplicate findings.
</ParamField>

<ParamField body="source" type="string">
  A label for the source, such as `crawler`, `paste`, or `telegram`. It
  appears in activity history and does not affect detection.
</ParamField>

<ParamField body="config" type="object">
  Optional detection and validation settings.

  <Expandable title="config">
    <ParamField body="rules" type="string[]">
      Run only the specified detection rule IDs. Omit this field to run every
      available rule.
    </ParamField>

    <ParamField body="min_severity" type="string">
      Return findings at or above `critical`, `high`, `medium`, or `low`.
    </ParamField>

    <ParamField body="baseline_fingerprints" type="string[]">
      Suppress findings you have already reviewed.
    </ParamField>

    <ParamField body="include_likely_false_positives" type="boolean">
      Include findings flagged as likely false positives.
    </ParamField>

    <ParamField body="max_findings" type="integer">
      Limit the number of findings returned.
    </ParamField>

    <ParamField body="validate" type="boolean">
      Check whether supported credentials still work. Omit this field to use the
      deployment default. Set it to `false` for detection only.
    </ParamField>
  </Expandable>
</ParamField>

<Warning>
  This endpoint scans only the supplied `content`. It does not fetch a URL.
  Use [GitHub Leaks](/api-reference/endpoint/github-leaks) to scan a public
  repository and its history.
</Warning>

## Example

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"vesper"}}
  curl -X POST "https://developer.encrata.com/api/lookup/breaches/exposed-keys" \
    -H "Authorization: Bearer enc_xxxxxxxxxxxx" \
    -H "Content-Type: application/json" \
    -d '{
      "content": "AWS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE",
      "source": "crawler",
      "config": {
        "validate": true,
        "min_severity": "medium"
      }
    }'
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"vesper"}}
  import requests

  response = requests.post(
      "https://developer.encrata.com/api/lookup/breaches/exposed-keys",
      headers={"Authorization": "Bearer enc_xxxxxxxxxxxx"},
      json={
          "content": "AWS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE",
          "source": "crawler",
          "config": {"validate": True, "min_severity": "medium"},
      },
  )
  response.raise_for_status()
  print(response.json())
  ```
</CodeGroup>

## Response

The endpoint always runs synchronously. A `200 OK` response uses the
`{success, result, message}` envelope.

```json theme={"theme":{"light":"github-light","dark":"vesper"}}
{
  "success": true,
  "result": {
    "scan_id": "8f4ae53c-8b72-4d63-93ef-5bb369a8e351",
    "repository_id": "3edce238-986c-4897-b088-826791967f52",
    "kind": "keys",
    "target": "sha256:8a2ff5c3...",
    "type": 0,
    "commit_sha": "8a2ff5c3...",
    "depth": 0,
    "config": {
      "min_severity": "medium",
      "validate": true
    },
    "summary": {
      "total": 1,
      "by_severity": {"high": 1},
      "by_engine": {"encrata intelligence": 1},
      "engines_run": ["encrata intelligence"],
      "rules_requested": 0,
      "duration_ms": 84,
      "suppressed": 0,
      "validated": 1,
      "live": 0,
      "truncated": false
    },
    "findings": [
      {
        "fingerprint": "b9d1...e2",
        "rule_id": "aws-access-key-id",
        "description": "AWS access key ID",
        "severity": "high",
        "severity_source": "engine",
        "engines": ["encrata intelligence"],
        "start_line": 1,
        "end_line": 1,
        "column": 19,
        "preview": "AKIA****************",
        "entropy": 3.8,
        "likely_false_positive": false,
        "validation": {
          "status": "invalid",
          "confidence": 1,
          "checked_at": "2026-10-07T09:30:00Z"
        }
      }
    ],
    "reused": false,
    "charged": true,
    "credits": 1
  },
  "message": "Scan complete. 1 exposed credential found."
}
```

<ResponseField name="success" type="boolean">
  Whether the scan completed.
</ResponseField>

<ResponseField name="message" type="string">
  A human-readable summary of the result.
</ResponseField>

<ResponseField name="result" type="object">
  The scan result.

  <Expandable title="result">
    <ResponseField name="scan_id" type="string">
      The stored scan ID.
    </ResponseField>

    <ResponseField name="repository_id" type="string">
      The internal target ID used to store and authorize the result.
    </ResponseField>

    <ResponseField name="kind" type="string">
      Always `keys` for this endpoint.
    </ResponseField>

    <ResponseField name="target" type="string">
      A SHA-256 identifier for the submitted content. The raw content is not
      stored in this field.
    </ResponseField>

    <ResponseField name="type" type="integer">
      The detection profile that ran: `0`, `1`, or `2`.
    </ResponseField>

    <ResponseField name="commit_sha" type="string">
      The SHA-256 digest of the submitted content.
    </ResponseField>

    <ResponseField name="depth" type="integer">
      Always `0`. Text scans have no repository history.
    </ResponseField>

    <ResponseField name="config" type="object">
      The effective configuration used for the scan.
    </ResponseField>

    <ResponseField name="summary" type="object">
      Counts and timing for the scan.

      <Expandable title="summary">
        <ResponseField name="total" type="integer">
          Number of findings returned.
        </ResponseField>

        <ResponseField name="by_severity" type="object">
          Finding counts grouped by severity.
        </ResponseField>

        <ResponseField name="by_engine" type="object">
          Finding counts grouped under `encrata intelligence`.
        </ResponseField>

        <ResponseField name="engines_run" type="string[]">
          Detection sources that ran.
        </ResponseField>

        <ResponseField name="rules_requested" type="integer">
          Number of requested rules. `0` means every available rule.
        </ResponseField>

        <ResponseField name="deep_scan" type="boolean">
          Omitted for this endpoint because text has no repository history.
        </ResponseField>

        <ResponseField name="duration_ms" type="integer">
          Scan duration in milliseconds.
        </ResponseField>

        <ResponseField name="suppressed" type="integer">
          Findings removed by rules, severity filters, or baseline fingerprints.
        </ResponseField>

        <ResponseField name="validated" type="integer">
          Findings that received a validation verdict.
        </ResponseField>

        <ResponseField name="live" type="integer">
          Validated credentials that still work.
        </ResponseField>

        <ResponseField name="truncated" type="boolean">
          Whether `max_findings` truncated the result.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="findings" type="object[]">
      Detected credentials. Raw credentials are never returned.

      <Expandable title="finding">
        <ResponseField name="fingerprint" type="string">
          Stable hash-derived ID for deduplication and baselines.
        </ResponseField>

        <ResponseField name="rule_id" type="string">
          Detection rule that matched.
        </ResponseField>

        <ResponseField name="description" type="string">
          Human-readable finding type.
        </ResponseField>

        <ResponseField name="severity" type="string">
          `critical`, `high`, `medium`, `low`, or `unknown`.
        </ResponseField>

        <ResponseField name="severity_source" type="string">
          `engine` or `unreported`.
        </ResponseField>

        <ResponseField name="engines" type="string[]">
          Detection sources that reported the location.
        </ResponseField>

        <ResponseField name="file" type="string">
          Source file name when the submitted text includes file context.
        </ResponseField>

        <ResponseField name="start_line" type="integer">
          1-based first line of the match.
        </ResponseField>

        <ResponseField name="end_line" type="integer">
          1-based last line of the match.
        </ResponseField>

        <ResponseField name="column" type="integer">
          1-based starting column.
        </ResponseField>

        <ResponseField name="preview" type="string">
          Masked preview of the credential.
        </ResponseField>

        <ResponseField name="entropy" type="number">
          Shannon entropy of the match.
        </ResponseField>

        <ResponseField name="commit" type="string">
          Commit SHA when source context contains one.
        </ResponseField>

        <ResponseField name="author" type="string">
          Commit author when source context contains one.
        </ResponseField>

        <ResponseField name="email" type="string">
          Commit author email when source context contains one.
        </ResponseField>

        <ResponseField name="date" type="string">
          Commit timestamp when source context contains one.
        </ResponseField>

        <ResponseField name="likely_false_positive" type="boolean">
          Whether the finding is flagged as a likely false positive.
        </ResponseField>

        <ResponseField name="validation" type="object">
          Live-credential check. Present only when validation ran.

          <Expandable title="validation">
            <ResponseField name="status" type="string">
              `valid`, `invalid`, or `undetermined`.
            </ResponseField>

            <ResponseField name="confidence" type="number">
              Confidence in the validation result.
            </ResponseField>

            <ResponseField name="checked_at" type="string">
              ISO 8601 timestamp for the validation check.
            </ResponseField>
          </Expandable>
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="reused" type="boolean">
      Whether an existing scan of identical content and configuration answered
      the request.
    </ResponseField>

    <ResponseField name="charged" type="boolean">
      Whether the request deducted credits.
    </ResponseField>

    <ResponseField name="credits" type="integer">
      Credits deducted. The cost is one credit per finding.
    </ResponseField>

    <ResponseField name="status" type="string">
      Omitted for this synchronous endpoint.
    </ResponseField>
  </Expandable>
</ResponseField>

## Read a stored scan

Read a previous result without rescanning or charging again:

```bash theme={"theme":{"light":"github-light","dark":"vesper"}}
curl "https://developer.encrata.com/api/lookup/breaches/exposed-keys/{scan_id}?min_severity=high" \
  -H "Authorization: Bearer enc_xxxxxxxxxxxx"
```

The optional `min_severity` query filters stored findings. It does not run the
scanner again.

## Errors

| Status | Cause |
| - | - |
| `400` | The JSON body cannot be read. |
| `401` | The API key is missing or invalid. |
| `402` | The account has no available credits. |
| `413` | `content` exceeds 256 KB. |
| `422` | `content` is empty, `type` is outside `0-2`, or a repository-only option was sent. |
| `502` | The scanner could not complete the request. |
| `503` | Secret scanning or the selected detection profile is unavailable. |
| `504` | The scan exceeded its time limit. |

## Credits

You pay **1 credit per exposed credential found**. A clean scan is free.
Submitting identical content with the same configuration reuses the stored scan,
so your account is not charged twice. See [Credits](/credits).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.