Download OpenAPI specification:
The DarkStrata API provides programmatic access to your organisation's threat intelligence and security operations. Use it to manage monitored assets and domains, query compromised credential data, configure alerts and automated actions, administer user and asset groups, integrate with third-party tools via webhooks, and export data for downstream analysis.
All API requests require an API key sent in the X-Api-Key header.
Sign up at app.darkstrata.io, generate an API key in Integrations > API Keys, and include it in your requests:
curl -X GET "https://api.darkstrata.io/v1/__gtg" \
-H "X-Api-Key: your_api_key_here" \
-H "Content-Type: application/json"
The DarkStrata API is also available as an MCP server for AI agents. Connect any MCP-compatible client to mcp.darkstrata.io/mcp using your API key to access tools, resources, and pre-built security workflows. See the MCP documentation for connection details.
All API endpoints support the Accept-Language header. Error messages, validation responses, and other user-facing text are returned in the requested locale.
Supported locales: en (default), ca, de, es, fr, it, ja, ko, nl, pl, sl, zh
If the requested locale is not supported, the API falls back to English (en).
curl -X GET "https://api.darkstrata.io/v1/alerts" \
-H "X-Api-Key: your_api_key_here" \
-H "Accept-Language: de"
All error responses follow a consistent structure with a machine-readable error code and a localised human-readable message:
{
"error": {
"code": "UNAUTHORIZED",
"message": "Invalid username or password"
}
}
Validation errors (HTTP 400) include field-level detail:
{
"message": "Invalid input data",
"errors": [
{ "field": "email", "message": "Must be a valid email address" }
]
}
Common error codes: BAD_REQUEST, UNAUTHORIZED, FORBIDDEN, NOT_FOUND, CONFLICT, RATE_LIMITED, PLAN_LIMIT_EXCEEDED, INTERNAL_SERVER_ERROR.
/alerts
| page | integer >= 1 Default: 1 Page number for pagination |
| limit | integer [ 1 .. 100 ] Default: 10 Number of items per page |
| status | string Enum: "ACTIVE" "UNDER_INVESTIGATION" "CLOSED" Filter by alert status |
| severity | string Enum: "INFO" "LOW" "MEDIUM" "HIGH" "CRITICAL" Filter by alert severity |
| alert_type | string Enum: "CREDENTIAL_EXPOSURE" "CONFIRMED_PASSWORD_USE" "CONFIRMED_SUPPLIER_PASSWORD_USE" "GHOST_SEEN" Filter by alert type |
| product | string Filter by product slug or public_id (e.g. stealer-intel) |
| from_date | string <date-time> Filter alerts from this date (ISO 8601) |
| to_date | string <date-time> Filter alerts to this date (ISO 8601) |
| tactic | string^TA[0-9]{4}$ Example: tactic=TA0006 MITRE ATT&CK® tactic id. Keeps alerts whose |
| technique | string^T[0-9]{4}(\.[0-9]{3})?$ Example: technique=T1555.003 MITRE ATT&CK® technique id (sub-techniques included, e.g. T1555.003). Keeps alerts whose |
| sort | string Default: "generated_at" Enum: "generated_at" "published_at" "acknowledged_at" "total_new_matches" "status" "severity" Field to sort by |
| direction | string Default: "desc" Enum: "asc" "desc" Sort direction |
| organisation | string <uuid> Filter by organisation public_id (requires access to the organisation) |
[- {
- "id": "550e8400-e29b-41d4-a716-446655440000",
- "title": "Credential Exposure: 3 Staff Accounts",
- "description": "3 staff accounts (3 with active malware) exposed across 1 asset.",
- "severity": "HIGH",
- "status": "ACTIVE",
- "alert_type": "CREDENTIAL_EXPOSURE",
- "from_date": "2026-10-18T00:00:00Z",
- "to_date": "2026-10-19T00:00:00Z",
- "generated_at": "2026-10-19T06:00:03Z",
- "published_at": "2026-10-19T06:00:03Z",
- "total_new_matches": 4,
- "unique_identifiers": 3,
- "unique_assets_count": 1,
- "stealer_match_count": 4,
- "breach_match_count": 0,
- "affected_assets": [
- {
- "id": "7f8d9e0a-1b2c-3d4e-5f6a-7b8c9d0e1f2a",
- "hostname": "example.com"
}
], - "breakdown_by_type": {
- "EP": 4
}, - "breakdown_by_source": {
- "MALWARE": 3
}, - "breakdown_by_flow": {
- "OUTBOUND": 3
}, - "mitre": {
- "attack_version": "20.0",
- "domain": "enterprise-attack",
- "techniques": [
- {
- "id": "T1555.003",
- "name": "Credentials from Web Browsers",
- "parent_name": "Credentials from Password Stores",
- "tactic_ids": [
- "TA0006"
], - "basis": "observed"
}, - {
- "id": "T1589.001",
- "name": "Credentials",
- "parent_name": "Gather Victim Identity Information",
- "tactic_ids": [
- "TA0043"
], - "basis": "observed"
}, - {
- "id": "T1539",
- "name": "Steal Web Session Cookie",
- "tactic_ids": [
- "TA0006"
], - "basis": "observed"
}
], - "software": [
- {
- "id": "S1240",
- "name": "RedLine Stealer",
- "basis": "observed"
}
]
}
}
]Distinct alert counts per ATT&CK tactic and technique over the last 90 days, read from each alert's mitre block. A technique under several tactics counts towards each. Alerts raised before ATT&CK tagging are not counted.
{- "attack_version": "20.0",
- "window_days": 90,
- "tagged_alerts": 12,
- "tactics": [
- {
- "id": "TA0043",
- "name": "Reconnaissance",
- "alert_count": 12
}, - {
- "id": "TA0006",
- "name": "Credential Access",
- "alert_count": 9
}
], - "techniques": [
- {
- "id": "T1589.001",
- "name": "Credentials",
- "parent_name": "Gather Victim Identity Information",
- "tactic_ids": [
- "TA0043"
], - "alert_count": 12
}, - {
- "id": "T1555.003",
- "name": "Credentials from Web Browsers",
- "parent_name": "Credentials from Password Stores",
- "tactic_ids": [
- "TA0006"
], - "alert_count": 9
}
]
}/alerts/{id}
| id required | string <uuid> Alert ID |
{- "id": "550e8400-e29b-41d4-a716-446655440000",
- "title": "Credential Exposure: 3 Staff Accounts",
- "description": "3 staff accounts (3 with active malware) exposed across 1 asset.",
- "severity": "HIGH",
- "status": "ACTIVE",
- "alert_type": "CREDENTIAL_EXPOSURE",
- "from_date": "2026-10-18T00:00:00Z",
- "to_date": "2026-10-19T00:00:00Z",
- "generated_at": "2026-10-19T06:00:03Z",
- "published_at": "2026-10-19T06:00:03Z",
- "total_new_matches": 4,
- "unique_identifiers": 3,
- "unique_assets_count": 1,
- "stealer_match_count": 4,
- "breach_match_count": 0,
- "affected_assets": [
- {
- "id": "7f8d9e0a-1b2c-3d4e-5f6a-7b8c9d0e1f2a",
- "hostname": "example.com"
}
], - "breakdown_by_type": {
- "EP": 4
}, - "breakdown_by_source": {
- "MALWARE": 3
}, - "breakdown_by_flow": {
- "OUTBOUND": 3
}, - "mitre": {
- "attack_version": "20.0",
- "domain": "enterprise-attack",
- "techniques": [
- {
- "id": "T1555.003",
- "name": "Credentials from Web Browsers",
- "parent_name": "Credentials from Password Stores",
- "tactic_ids": [
- "TA0006"
], - "basis": "observed"
}, - {
- "id": "T1589.001",
- "name": "Credentials",
- "parent_name": "Gather Victim Identity Information",
- "tactic_ids": [
- "TA0043"
], - "basis": "observed"
}, - {
- "id": "T1539",
- "name": "Steal Web Session Cookie",
- "tactic_ids": [
- "TA0006"
], - "basis": "observed"
}
], - "software": [
- {
- "id": "S1240",
- "name": "RedLine Stealer",
- "basis": "observed"
}
]
}, - "domains": [
- {
- "hostname": "example.com",
- "subdomain": null,
- "matches": 3
}, - {
- "hostname": "example.com",
- "subdomain": "mail",
- "matches": 1
}
]
}/alerts/{id}
| id required | string <uuid> Alert ID |
| status required | string Enum: "ACTIVE" "UNDER_INVESTIGATION" "CLOSED" New status for the alert |
{- "status": "ACTIVE"
}{- "id": "550e8400-e29b-41d4-a716-446655440000",
- "status": "CLOSED",
- "updated_at": "2024-01-15T09:45:00Z",
- "acknowledged_at": "2024-01-08T15:30:00Z",
- "closed_at": "2024-01-15T09:45:00Z",
- "acknowledged_by_user": {
- "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
- "name": "John Smith",
- "email": "[email protected]"
}, - "closed_by_user": {
- "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
- "name": "Jane Doe",
- "email": "[email protected]"
}, - "last_modified_by_user": {
- "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
- "name": "Jane Doe",
- "email": "[email protected]"
}
}An API key may only mint keys for a tenant whose parent is an MSP partner, never for its own organisation. Target the tenant with organisation (or the x-impersonate-organisation header). The new key's permissions are capped at the calling key's. The secret is returned once.
| label | string [ 3 .. 64 ] characters |
| organisation | string <uuid> Tenant organisation ID |
| scope | Array of strings Permissions for the key; empty grants everything the tenant and the calling key allow |
| expires_at | string <date-time> |
| description | string <= 256 characters |
| accept_non_commercial_terms | boolean Required when the tenant has no billing contract |
{- "label": "string",
- "organisation": "a4b97354-4e56-4723-bc0e-1f22b5fcbed6",
- "scope": [
- "string"
], - "expires_at": "2019-08-24T14:15:22Z",
- "description": "string",
- "accept_non_commercial_terms": true
}Replaces the secret of the API key used to authenticate this request. The key keeps its ID, name, and permissions; the old secret stops working immediately. The new secret is returned once and cannot be retrieved again. Only API-key sessions can call this endpoint.
{- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "key": "string",
- "prefix": "string",
- "permissions": [
- "string"
]
}/assets
| page | integer >= 1 Default: 1 Page number for pagination |
| limit | integer [ 1 .. 100 ] Default: 10 Number of items per page |
| keyword | string Filter assets by hostname keyword |
| status | string Enum: "VERIFIED" "UNVERIFIED" "ERROR" Filter by verification status |
| method | string Enum: "DNS" "HTTP" Filter by verification method |
| sort | string Default: "created_at" Field to sort by |
| direction | string Default: "desc" Sort direction |
[- {
- "id": "7f8d9e0a-1b2c-3d4e-5f6a-7b8c9d0e1f2a",
- "hostname": "example.com",
- "is_enabled": true,
- "created_at": "2024-01-15T10:00:00.000Z",
- "verification": {
- "value": "darkstrata-verify=abc123def456",
- "status": "VERIFIED",
- "method": "DNS",
- "message": "DNS record verified successfully"
}, - "preferences": {
- "userFormats": {
- "inbound": true,
- "outbound": false
}
}, - "polling_status": {
- "status": "SUCCESS",
- "last_polled_at": "2024-01-20T14:30:00.000Z"
}
}, - {
- "id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
- "hostname": "subdomain.example.com",
- "is_enabled": true,
- "created_at": "2024-01-18T08:45:00.000Z",
- "verification": {
- "value": "darkstrata-verify=xyz789ghi012",
- "status": "UNVERIFIED",
- "method": "DNS",
- "message": "Waiting for DNS propagation"
}, - "preferences": {
- "userFormats": {
- "inbound": false,
- "outbound": true
}
}, - "polling_status": null
}
]/assets/bulk/resubmit-dns
| ids required | Array of strings <uuid> [ items <uuid > ] Array of asset IDs to resubmit DNS verification |
{- "ids": [
- "497f6eca-6276-4993-bfeb-53cbbbba6f08"
]
}/assets/{id}
| id required | string <uuid> Asset ID |
{- "id": "7f8d9e0a-1b2c-3d4e-5f6a-7b8c9d0e1f2a",
- "hostname": "example.com",
- "created_at": "2024-01-01T10:00:00Z",
- "verification": {
- "status": "VERIFIED",
- "method": "DNS",
- "message": "DNS record verified successfully"
}
}/assets/{id}/resubmit-dns
| id required | string Asset ID |
{- "message": "DNS checking can only be resubmitted for assets in failed verification state (ERROR). Current state does not qualify for resubmission.",
- "current_status": "VERIFIED"
}Returns aggregate statistics about the credential database including unique record counts and last update time.
SDKs: Official SDKs are available at: https://github.com/darkstrata/darkstrata-sdks
{- "unique_records": 15000000000,
- "total_records": 25000000000,
- "last_updated": "2024-12-15T10:30:00.000Z"
}Privacy-preserving credential breach checking service using k-anonymity.
How it works:
SHA256(email:password)Privacy guarantees:
Full documentation and examples: For complete end-to-end implementation examples and detailed usage guide, login to the Admin UI: https://app.darkstrata.io/explorer/credentials-api
SDKs: Official SDKs are available at: https://github.com/darkstrata/darkstrata-sdks
| prefix required | string [ 5 .. 6 ] characters ^[a-fA-F0-9]{5,6}$ Example: prefix=5baa61 First 5 or 6 hexadecimal characters of the SHA-256 hash to check. Case-insensitive (automatically normalised to uppercase). Using 6 characters returns ~16x fewer results than 5, reducing response size. Examples:
|
| clientHmac | string >= 64 characters ^[a-fA-F0-9]{64,}$ Example: clientHmac=8a2f7b9e1c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f Optional: Client-provided HMAC key for deterministic, consistent results across requests. Use case: Some customers need consistent hash results over time for tracking or caching purposes. By providing your own HMAC key, the returned hashes will always be the same for the same input data, enabling result caching and comparison across time. Security requirements:
If omitted or invalid: Falls back to server-generated HMAC with hourly rotation (time-windowed). Best practices:
Example generation (bash):
|
| since | integer >= 0 Example: since=20089 Optional: Filter results to only include entries added on or after this date. Accepts either:
Auto-detection: Values > 100000 are treated as Unix timestamps and converted. Use cases:
Example:
Note: If omitted, returns all matching entries regardless of when they were added. |
[- "8A2F7B9E1C3D4E5F6A7B8C9D0E1F2A3B4C5D6E7F8A9B0C1D2E3F4A5B6C7D8E9F",
- "B3C4D5E6F7A8B9C0D1E2F3A4B5C6D7E8F9A0B1C2D3E4F5A6B7C8D9E0F1A2B3C4",
- "C5D6E7F8A9B0C1D2E3F4A5B6C7D8E9F0A1B2C3D4E5F6A7B8C9D0E1F2A3B4C5D6"
]Aggregates the organisation's infostealer credential-exposure events (across its verified monitored assets) into headline metrics: total vs critical events, customers (inbound) vs employees (outbound), and the most-exposed services. The "breach" figure under sources counts third-party breach-corpus exposures (breach_exposures) for the org — surfaced alongside infostealer for comparison but NOT included in the infostealer event total (breaches carry no employee/ customer attribution). Suppressed when source=MALWARE. Only actionable records (status NEW or RE_EMERGED) are counted; triaged-away records (RESOLVED, IGNORED, FALSE_POSITIVE) are excluded, mirroring the explorer's default view.
| from | string Inclusive start of the event date range (ISO 8601). Omit for all-time. |
| to | string Inclusive end of the event date range (ISO 8601). Omit for all-time. |
| asset_ids | string Comma-separated asset public IDs to scope the summary to. |
| source | string Enum: "MALWARE" "BREACH" Restrict to a single source type (MALWARE = infostealer, BREACH = data breach). |
| top_limit | string Default: "5" Number of services to return in top_services (1-25). |
{- "events": {
- "total": 0,
- "critical": 0
}, - "distribution": {
- "customers": 0,
- "employees": 0
}, - "sources": {
- "infostealer": 0,
- "breach": 0
}, - "top_services": [
- {
- "service": "string",
- "count": 0
}
]
}Counts of breach exposures (BreachExposure rows) for the
calling organisation, broken down by status, threat score,
and combolist-vs-genuine corpus. Companion to
/data-intelligence/stats which covers stealer-log data;
this endpoint covers the second OUTBOUND data source —
third-party breaches indexed against monitored hostnames.
PII is never returned, only presence flags.
| hostnames | string Comma-separated monitored hostnames |
| threat_scores | string Comma-separated breach threat score levels (1-5) |
| identifier_status | string Comma-separated statuses (NEW, RESOLVED, IGNORED, FALSE_POSITIVE, RE_EMERGED) |
| is_combolist | string Enum: "true" "false" Restrict to combolist or genuine-breach corpora only |
| has_plaintext_password | string Enum: "true" "false" Restrict to rows with a recovered plaintext password |
| identifier_keyword | string Substring match against identifier (case-insensitive) |
| alert_id | string Scope results to the breach exposures that contributed to a specific alert (public_id). Joins through organisation_alert_matches. Returns zero rows if the alert does not exist or has no breach matches. |
| group_by | string Value: "identifier" When 'identifier', aggregate stats at the (identifier, asset) level so the headline numbers match the grouped table view (dominant status per group, max threat score per group, any-flag for combolist/plaintext). |
{- "message": "Invalid input data",
- "errors": [
- {
- "field": "email",
- "message": "Must be a valid email address"
}
]
}Paginated list of BreachExposure rows for the calling
organisation. Each row carries presence flags for every PII
field (booleans only — values are never stored or returned),
the corpus combolist flag, the password-strength score (null
until PasswordStrengthWorker has scored it), and the breach
threat score level. Companion to /data-intelligence/query,
which covers stealer logs.
Response is a discriminated union on mode:
mode: "rows" — one row per exposure (default)mode: "identifiers" — one row per identifier (when group_by=identifier),
with aggregated counts. Filters are pre-group: e.g.
threat_scores=5 returns identifiers whose at-least-one
child exposure is level 5, not those whose worst is 5.| page | string |
| limit | string |
| sort | string Enum: "last_seen_at" "first_seen_at" "breach_threat_score_level_id" "identifier" "corpus_breach_year" |
| direction | string Enum: "asc" "desc" |
| hostnames | string |
| threat_scores | string |
| identifier_status | string |
| is_combolist | string Enum: "true" "false" |
| has_plaintext_password | string Enum: "true" "false" |
| identifier_keyword | string |
| alert_id | string Scope results to the breach exposures that contributed to a specific alert (public_id). Joins through organisation_alert_matches. Returns zero rows if the alert does not exist or has no breach matches. |
| group_by | string Value: "identifier" When set to |
| format | string Default: "json" Enum: "json" "csv" Response format. |
| csv_fields | string Comma-separated list of CSV field names to include (e.g., "public_id,identifier,hostname"). When omitted, all fields are exported. Ignored for json responses. |
{- "message": "Invalid input data",
- "errors": [
- {
- "field": "email",
- "message": "Must be a valid email address"
}
]
}Updates the status on a set of BreachExposure rows in one
request. Accepts EITHER public_ids (direct list of
exposures) OR identifier_groups (each entry fans out to
every child exposure matching identifier+asset within the
caller's organisation — the entry-point for the grouped
view's bulk actions). Mixed payloads are rejected. Status
transitions follow the same closed-state bookkeeping as the
single-row PATCH (resolved_at / status_changed_at). Audit
events are emitted one per affected child row, tagged with
bulk_group_identifier when the identifier_groups path was
used so the timeline UI can collapse them.
| status required | string Enum: "NEW" "RESOLVED" "IGNORED" "FALSE_POSITIVE" "RE_EMERGED" |
| public_ids | Array of strings <uuid> [ items <uuid > ] Direct list of BreachExposure public_ids to update. |
Array of objects Each entry expands to every child exposure matching identifier+asset within the org. |
{- "status": "NEW",
- "public_ids": [
- "497f6eca-6276-4993-bfeb-53cbbbba6f08"
], - "identifier_groups": [
- {
- "identifier": "string",
- "asset_id": "b4695157-0d1d-4da0-8f9e-5c53149389e4"
}
]
}{- "affected": 0,
- "status": "string"
}Returns the human-readable signals that produced each child
exposure's score plus the identifier-level signals that may
have bumped or capped them. Mirrors the inputs of the worker
scorer (platform/workers/.../breach-exposure/scoring.ts)
but does not re-score — the stored breach_threat_score_level_id
is the source of truth.
| identifier required | string Identifier (email / username). Normalised to lowercase server-side. |
| asset_id required | string Asset public_id. Must belong to the caller's organisation. |
{- "identifier": "string",
- "asset": {
- "public_id": "string",
- "hostname": "string"
}, - "max_score": 0,
- "overall_reasons": [
- "string"
], - "exposures": [
- {
- "public_id": "string",
- "corpus_id": 0,
- "corpus_name": "string",
- "corpus_customer_display_allowed": true,
- "corpus_breach_year": 0,
- "corpus_is_combolist": true,
- "corpus_tier": "string",
- "corpus_authenticity": "string",
- "score": 0,
- "reasons": [
- "string"
]
}
]
}/data-intelligence/stats
| flow | string Enum: "INBOUND" "OUTBOUND" Filter by data flow direction |
| months | number [ 1 .. 12 ] Default: 6 Number of months to include in trends |
| asset_id | string Filter by asset ID |
| is_matching_naming_rule | string Enum: "true" "false" Filter by naming rule match |
| show_junk | string Enum: "true" "false" Include junk records in statistics |
| start_date | string <date-time> Filter by start date (ISO 8601 format) |
| end_date | string <date-time> Filter by end date (ISO 8601 format) |
| credential_type | string Enum: "EP" "UP" Filter by credential type |
| keyword | string Search by identifier keyword (case-insensitive) |
| is_matching_groups | string Enum: "true" "false" Filter by group member match status |
| threat_score | string Filter by exact threat score level (1-5, where 1=Info, 2=Needs Review, 3=Medium, 4=High, 5=Critical) |
| threat_score_min | string Minimum threat score filter (inclusive, 1-5) |
| threat_score_max | string Maximum threat score filter (inclusive, 1-5) |
| threat_scores | string Comma-separated list of threat score levels to include (e.g., "1,2,3,4,5") |
| hostnames | string Comma-separated list of full hostnames to filter by (e.g., "mail.example.com,portal.example.com"). For INBOUND flow, filters by the constructed hostname (subdomain + apex domain). Only valid hostname characters are accepted (alphanumeric, dots, hyphens). |
| alert_id | string Scope stats to the stealer-log records that contributed to a specific alert (public_id). |
{- "overview": {
- "total_users": 1247,
- "flow_filter": "INBOUND"
}, - "trends": {
- "monthly_users": [
- {
- "month": "Aug 2024",
- "users": 892
}, - {
- "month": "Sep 2024",
- "users": 945
}, - {
- "month": "Oct 2024",
- "users": 1023
}, - {
- "month": "Nov 2024",
- "users": 1089
}, - {
- "month": "Dec 2024",
- "users": 1156
}, - {
- "month": "Jan 2025",
- "users": 1247
}
]
}, - "metrics": {
- "average_junk_score": 23,
- "average_threat_score": 2.5,
- "average_password_strength": 2.8,
- "matching_naming_rule_count": 856,
- "total_password_variants": 3421,
- "average_password_variants_per_identifier": 2.74,
- "identifiers_with_multiple_passwords": 892
}, - "groups": {
- "matched_count": 423
}, - "domains": {
- "total": 5,
- "affected_domains": [
- {
- "public_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
- "hostname": "example.com"
}, - {
- "public_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
- "hostname": "subdomain.example.com"
}, - {
- "public_id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
- "hostname": "another.example.com"
}
]
}, - "services": {
- "unique_service_roots": 127,
- "score": 42.5,
- "risk": {
- "critical": 3,
- "high": 12,
- "medium": 45,
- "low": 67
}, - "categories": [
- "social networks",
- "cloud storage",
- "productivity tools",
- "communication",
- "entertainment"
]
}, - "threat_score_stats": {
- "total_records": 2500,
- "ranked_records": 1247,
- "filtered_records": 1253
}
}Fetches all unique hostnames (subdomain + apex domain) with their credential match counts for INBOUND flow (Compromised Customers). Use this endpoint to populate hostname filter pills in the UI. A hostname is the full domain name including any subdomain prefix (e.g., "mail.example.com" or just "example.com" if no subdomain).
| asset_id | string Optional asset public ID to filter hostnames for a specific monitored asset |
| alert_id | string Scope hostnames to the stealer-log records that contributed to a specific alert (public_id). Joins through organisation_alert_matches. Returns zero rows if the alert does not exist or has no stealer matches. |
| keyword | string Search by identifier keyword (case-insensitive) |
| hostname_search | string Substring filter against hostname (case-insensitive) |
| show_junk | string Enum: "true" "false" Include low-quality/junk records |
| start_date | string <date-time> Filter by start date (ISO 8601 format) |
| end_date | string <date-time> Filter by end date (ISO 8601 format) |
| credential_type | string Enum: "EP" "UP" Filter by credential type |
| is_matching_naming_rule | string Enum: "true" "false" Filter by naming rule match |
| is_matching_groups | string Enum: "true" "false" Filter by group member match status |
| threat_scores | string Comma-separated list of threat score levels to include (e.g., "1,2,3,4,5") |
| identifier_status | string Comma-separated identifier status filter (NEW, RESOLVED, IGNORED, FALSE_POSITIVE, RE_EMERGED, FLAGGED) |
| is_password_reuser | string Enum: "true" "false" Filter to only show identifiers who reuse passwords across different services |
{- "hostnames": [
- {
- "hostname": "portal.example.com",
- "match_count": 15
}, - {
- "hostname": "mail.example.com",
- "match_count": 8
}, - {
- "hostname": "example.com",
- "match_count": 3
}
], - "total_match_count": 26
}/data-intelligence/query
| page | integer >= 1 Default: 1 Page number for pagination |
| limit | integer [ 1 .. 100 ] Default: 10 Number of items per page |
| asset_id | string Filter by asset ID |
| alert_id | string Scope results to the stealer-log records that contributed to a specific alert (public_id). Joins through organisation_alert_matches. Returns zero rows if the alert does not exist or has no stealer matches. |
| group_ids | Array of strings Filter by specific group IDs |
| include_password_variants | string Enum: "true" "false" Include password variants in response |
| junk_score_min | string Minimum junk score filter |
| junk_score_max | string Maximum junk score filter |
| keyword | string Search by identifier keyword (case-insensitive) |
| start_date | string <date-time> Filter by start date (ISO 8601 format) |
| end_date | string <date-time> Filter by end date (ISO 8601 format) |
| flow | string Enum: "INBOUND" "OUTBOUND" Filter by flow direction. If not specified, returns all flows. |
| credential_type | string Enum: "EP" "UP" Filter by credential type |
| type | string Default: "json" Enum: "json" "csv" Response type. |
| csv_fields | string Comma-separated CSV columns (default: all). Available: id, asset_id, hostname, identifier, junk_score, threat_score, base_threat_score, provenance_label, matched_corpora_count, earliest_match_year, combolist_confidence, is_matching_naming_rule, is_logging_into_monitored_asset, is_in_any_group, is_in_priority_group, password_strength_score, credential_type, service_type, source, flow, created_at, matched_member_id, matched_group_name, matched_at, asset_group_name, asset_group_category, identifier_domain_group_name, identifier_domain_group_category, matched_service_count, password_variant_count. |
| sort | string Enum: "identifier" "domain" "junk_score" "threat_score_level_id" "created_at" "effective_priority" "matched_service_count" Sort field (default effective_priority DESC — actionable items first, then by threat score) |
| direction | string Enum: "asc" "desc" "ASC" "DESC" Sort direction (case insensitive) |
| is_matching_naming_rule | string Enum: "true" "false" Filter by naming rule match |
| is_matching_groups | string Enum: "true" "false" Filter by group member match status |
| threat_score | string Filter by exact threat score level (1-5, where 1=Info, 2=Needs Review, 3=Medium, 4=High, 5=Critical) |
| threat_score_min | string Minimum threat score filter (inclusive, 1-5) |
| threat_score_max | string Maximum threat score filter (inclusive, 1-5) |
| threat_scores | string Comma-separated list of threat score levels to include (e.g., "1,2,3,4,5") |
| identifier_status | string Comma-separated identifier status filter — NEW, RESOLVED, IGNORED, FALSE_POSITIVE, RE_EMERGED. Use "FLAGGED" to show all non-NEW statuses. |
| is_password_reuser | string Enum: "true" "false" Filter to only show identifiers who reuse passwords across different services |
| hostnames | string Comma-separated list of full hostnames to filter by (e.g., "mail.example.com,portal.example.com"). For INBOUND flow, filters by the constructed hostname (subdomain + apex domain). Only valid hostname characters are accepted (alphanumeric, dots, hyphens). |
[- {
- "id": "ddm_abc123xyz",
- "credential_type": "EP",
- "created_at": "2024-01-15T08:30:00Z",
- "threat_score": {
- "level": 4,
- "is_matching_naming_rule": true,
- "is_logging_into_monitored_asset": true,
- "is_in_any_group": true,
- "is_in_priority_group": true
}, - "metrics": {
- "junk_score": 15,
- "password_strength_score": 3
}, - "classification": {
- "source": "BREACH_DB_2024_01",
- "service_type": "BREACH",
- "flow": "INBOUND"
}, - "asset": {
- "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
- "hostname": "example.com",
- "subdomain": "mail"
}, - "group_matching": [
- {
- "id": "gm_xyz789abc",
- "name": "Engineering Team",
- "is_priority": true,
- "matched_at": "2024-01-15T08:35:00Z"
}, - {
- "id": "gm_def456ghi",
- "name": "All Employees",
- "is_priority": false,
- "matched_at": "2024-01-15T08:35:00Z"
}
]
}, - {
- "id": "ddm_def456uvw",
- "credential_type": "UP",
- "created_at": "2024-01-14T14:22:00Z",
- "threat_score": {
- "level": 1,
- "is_matching_naming_rule": true,
- "is_logging_into_monitored_asset": false,
- "is_in_any_group": false,
- "is_in_priority_group": false
}, - "metrics": {
- "junk_score": 8,
- "password_strength_score": 4
}, - "classification": {
- "source": "STEALER_LOG_XYZ",
- "service_type": "STEALER",
- "flow": "INBOUND"
}, - "asset": {
- "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
- "hostname": "subdomain.example.com"
}, - "group_matching": [ ]
}
]Returns stealer-side activity for the identifier plus a
breach_exposures array — one row per third-party-corpus
exposure linked to this identifier (same row shape as
/data-intelligence/breaches/query mode: rows). Capped at
200 rows; breach_exposure_count_truncated is true when the
cap was hit.
| id required | string The public_id (GUID) of a domain data match record |
| asset_id | string Optional asset public_id to scope the lookup |
Performs a soft delete on multiple domain data match records by setting deleted_at timestamp. Records are not permanently deleted but will be excluded from all queries and statistics. Maximum of 2000 records can be deleted in a single request.
| ids required | Array of strings [ 1 .. 2000 ] items Array of public IDs to soft delete (maximum 2000) |
{- "ids": [
- "string"
]
}{- "message": "string",
- "deleted_count": 0
}/data-intelligence/identifiers/{id}
| id required | string Public ID of the identifier record |
| status | string Enum: "NEW" "RESOLVED" "IGNORED" "FALSE_POSITIVE" "RE_EMERGED" |
| notes | string or null |
| tags | Array of strings |
{- "status": "NEW",
- "notes": "string",
- "tags": [
- "string"
]
}Retrieves the completion status of recommended actions for an identifier record
| id required | string Public ID of the identifier record |
| flow | string Enum: "INBOUND" "OUTBOUND" Flow direction — if omitted, auto-detected from match data |
{- "actions": [
- {
- "action_key": "reset_passwords",
- "completed": true,
- "completed_at": "2019-08-24T14:15:22Z",
- "completed_by": {
- "id": "string",
- "name": "string"
}, - "is_automatic": true
}
], - "completed_count": 0,
- "total_count": 0
}Updates the completion status of recommended actions for an identifier record
| id required | string Public ID of the identifier record |
| flow | string Enum: "INBOUND" "OUTBOUND" Flow direction — if omitted, auto-detected from match data |
required | Array of objects |
{- "actions": [
- {
- "action_key": "reset_passwords",
- "completed": true
}
]
}{- "message": "string",
- "actions": [
- {
- "action_key": "string",
- "completed": true,
- "completed_at": "2019-08-24T14:15:22Z",
- "completed_by": {
- "id": "string",
- "name": "string"
}, - "is_automatic": true
}
], - "completed_count": 0,
- "total_count": 0
}Group management for organising users and assets. Groups can be of two types:
Retrieve a paginated list of groups within your organisation. Groups can be filtered by type:
| page | integer >= 1 Default: 1 Page number for pagination |
| limit | integer [ 1 .. 100 ] Default: 10 Number of items per page |
| keyword | string Filter groups by name keyword |
| sync_source | string Enum: "MANUAL" "GOOGLE_GROUPS" "GOOGLE_WORKSPACE" "AZURE_AD" "ACTIVE_DIRECTORY" "LDAP" "BULK_IMPORT" "API" Filter by sync source |
| group_type | string Enum: "USERS" "ASSETS" Filter by group type. USERS groups contain user identities (email, username, etc.), ASSETS groups contain hostnames or asset identifiers. |
| sync_status | string Enum: "ACTIVE" "DISABLED" "ERROR" "PENDING_SETUP" Filter by sync status |
| sort | string Default: "created_at" Field to sort by |
| direction | string Default: "desc" Sort direction |
[- {
- "id": "550e8400-e29b-41d4-a716-446655440000",
- "name": "Engineering Team",
- "description": "All engineering staff members",
- "is_priority": true,
- "group_type": "USERS",
- "sync_source": "GOOGLE_WORKSPACE",
- "sync_status": "ACTIVE",
- "sync_error": null,
- "last_synced_at": "2025-11-06T10:30:00.000Z",
- "member_count": 42,
- "created_at": "2025-10-01T08:00:00.000Z",
- "updated_at": "2025-11-06T10:30:00.000Z"
}, - {
- "id": "660e8400-e29b-41d4-a716-446655440001",
- "name": "Marketing Team",
- "description": null,
- "is_priority": false,
- "group_type": "USERS",
- "sync_source": "MANUAL",
- "sync_status": "ACTIVE",
- "sync_error": null,
- "last_synced_at": null,
- "member_count": 15,
- "created_at": "2025-10-15T14:20:00.000Z",
- "updated_at": "2025-10-20T09:15:00.000Z"
}, - {
- "id": "770e8400-e29b-41d4-a716-446655440002",
- "name": "Production Servers",
- "description": "Critical production infrastructure",
- "is_priority": true,
- "group_type": "ASSETS",
- "sync_source": "MANUAL",
- "sync_status": "ACTIVE",
- "sync_error": null,
- "last_synced_at": null,
- "member_count": 25,
- "created_at": "2025-11-01T09:00:00.000Z",
- "updated_at": "2025-11-05T16:45:00.000Z"
}
]/groups
| name required | string [ 1 .. 255 ] characters Group name (must be unique within organisation) |
| description | string <= 1000 characters Optional group description |
| is_priority | boolean Default: false Whether this is a priority group |
| group_type | string Default: "USERS" Enum: "USERS" "ASSETS" Type of group. Use USERS for user/identity groups (email, username, employee ID, phone, custom identifiers). Use ASSETS for hostname/asset groups. Asset groups only support manual member management. |
| sync_source | string Default: "MANUAL" Enum: "MANUAL" "GOOGLE_GROUPS" "GOOGLE_WORKSPACE" "AZURE_AD" "ACTIVE_DIRECTORY" "LDAP" "BULK_IMPORT" "API" Source of group synchronization. Note that ASSETS groups only support MANUAL sync. |
| sync_config | object Sync-specific configuration (JSON object) |
{- "name": "Security Team",
- "description": "Information security and compliance team",
- "is_priority": true,
- "group_type": "USERS",
- "sync_source": "MANUAL",
- "sync_config": { }
}{- "id": "770e8400-e29b-41d4-a716-446655440002"
}/groups/{id}
| id required | string <uuid> Group ID |
{- "id": "550e8400-e29b-41d4-a716-446655440000",
- "name": "Engineering Team",
- "description": "All engineering staff members",
- "group_type": "USERS",
- "sync_source": "GOOGLE_WORKSPACE",
- "sync_status": "ACTIVE",
- "sync_error": null,
- "last_synced_at": "2025-11-06T10:30:00.000Z",
- "member_count": 42,
- "created_at": "2025-10-01T08:00:00.000Z",
- "updated_at": "2025-11-06T10:30:00.000Z"
}/groups/{id}
| id required | string <uuid> Group ID |
| name | string |
| description | string |
| sync_source | string Enum: "MANUAL" "GOOGLE_GROUPS" "GOOGLE_WORKSPACE" "AZURE_AD" "ACTIVE_DIRECTORY" "LDAP" "BULK_IMPORT" "API" |
| sync_config | object |
| sync_status | string Enum: "ACTIVE" "DISABLED" "ERROR" "PENDING_SETUP" |
{- "name": "string",
- "description": "string",
- "sync_source": "MANUAL",
- "sync_config": { },
- "sync_status": "ACTIVE"
}Upload group members using multiple formats: JSON, CSV (inline or file upload).
Group Types:
USERS groups: Members are user identities (emails, usernames, employee IDs, etc.)ASSETS groups: Members are hostnames or asset identifiersModes:
add (default): Appends new members to existing onesreplace: Removes all existing members first, then adds the new onesCSV Format Options:
identifier, identifier_type, display_name, external_id, metadataemail, username, user, member, or hostname are auto-detectedjob_title, department, company_name, employee_id, employee_type,
office_location, city, country, manager_name, manager_email, mobile_phone, business_phone.
Header matching is case-insensitive and ignores spaces/underscores (Job Title, job_title and jobTitle are equivalent).
Values are stored in member metadata under the same keys populated by Entra ID and Google Workspace sync,
so manually imported and directory-synced members are enriched identically. Empty cells are ignored.Content-Type Options:
application/json: Standard JSON with members arraytext/csv: CSV content in request bodytext/plain: Plain text CSV contentmultipart/form-data: Upload CSV fileLimits:
| id required | string <uuid> Group ID |
| mode | string Default: "add" Enum: "add" "replace" add: Append new members (duplicates ignored) replace: Remove all existing members and add new ones |
required | Array of objects [ 1 .. 1000 ] items |
{- "members": [
]
}{- "added_count": 45,
- "duplicate_count": 5,
- "removed_count": 20,
- "total_submitted": 50,
- "message": "45 members added successfully, 5 duplicates ignored"
}/groups/{id}/members
| id required | string <uuid> Group ID |
| page | integer >= 1 Default: 1 Page number for pagination |
| limit | integer [ 1 .. 100 ] Default: 10 Number of items per page |
| keyword | string Filter members by identifier or display name |
| identifier_type | string Enum: "EMAIL" "USERNAME" "EMPLOYEE_ID" "PHONE" "CUSTOM" "HOSTNAME" Filter by identifier type. For USERS groups use EMAIL, USERNAME, EMPLOYEE_ID, PHONE, or CUSTOM. For ASSETS groups use HOSTNAME. |
| status | string Enum: "ACTIVE" "INACTIVE" "PENDING" "REMOVED" Filter by member status |
| sort | string Default: "added_at" Field to sort by |
| direction | string Default: "desc" Sort direction |
[- {
- "id": "880e8400-e29b-41d4-a716-446655440010",
- "identifier_type": "EMAIL",
- "display_name": "Alice Johnson",
- "status": "ACTIVE",
- "sync_source": "GOOGLE_WORKSPACE",
- "external_id": "emp-001",
- "metadata": {
- "jobTitle": "Senior Engineer",
- "department": "Engineering",
- "managerEmail": "[email protected]"
}, - "added_at": "2025-10-01T09:00:00.000Z",
- "updated_at": "2025-10-01T09:00:00.000Z"
}, - {
- "id": "990e8400-e29b-41d4-a716-446655440011",
- "identifier_type": "EMAIL",
- "display_name": "Bob Williams",
- "status": "ACTIVE",
- "sync_source": "MANUAL",
- "external_id": null,
- "metadata": { },
- "added_at": "2025-10-15T10:30:00.000Z",
- "updated_at": "2025-10-15T10:30:00.000Z"
}
]/groups/{id}/members/{member_id}
| id required | string <uuid> Group ID |
| member_id required | string <uuid> Member ID |
| display_name | string |
| status | string Enum: "ACTIVE" "INACTIVE" "PENDING" "REMOVED" |
| external_id | string |
| metadata | object |
{- "display_name": "string",
- "status": "ACTIVE",
- "external_id": "string",
- "metadata": { }
}/groups/{id}/members/move
| id required | string <uuid> Source group ID |
| target_group_id required | string <uuid> Target group ID to move members to |
| member_ids required | Array of strings <uuid> [ items <uuid > ] Array of member IDs to move |
{- "target_group_id": "efc47beb-e46d-465e-921d-3e02578ccf22",
- "member_ids": [
- "497f6eca-6276-4993-bfeb-53cbbbba6f08"
]
}{- "moved_count": 0,
- "duplicate_count": 0,
- "message": "string"
}Request a new incident response export for an apex domain. This will search for outbound credential data across the domain and all its subdomains, package it into an encrypted archive, and make it available for download. Exports are subject to an annual quota. Freemail domains (e.g. gmail.com, yahoo.com) and popular public domains (e.g. google.com, facebook.com) are blocked. This feature is not available on standard plans and is only enabled for approved partners. Contact hello@darkstrata.io to enable this feature.
| domain required | string Apex domain to export credential data for (e.g. example.com). Subdomains are automatically stripped. |
| attestation_full_name required | string [ 2 .. 200 ] characters Full legal name of the person making the attestation |
| attestation_title required | string [ 2 .. 200 ] characters Job title of the person making the attestation |
| attestation_company required | string [ 2 .. 200 ] characters Company of the person making the attestation |
| attestation_reason_type required | string Enum: "PENTEST" "SECURITY_AUDIT" "INCIDENT_RESPONSE" "COMPLIANCE" "LEGAL_REQUEST" "OTHER" Reason for requesting the export |
| attestation_reason | string <= 2000 characters Additional justification (required when reason_type is OTHER) |
| attestation_accepted required | boolean Value: true Must be true to confirm legal attestation |
| encryption_method | string Enum: "PASSWORD_ZIP" "SEVEN_ZIP" "PGP" Archive encryption method. Defaults to PGP when pgp_key_id is supplied, otherwise PASSWORD_ZIP. PGP requires pgp_key_id. |
| pgp_key_id | string <uuid> Public ID of the organisation PGP key to encrypt with (from GET /organisations/{id}/pgp-keys). Required when encryption_method is PGP. |
{- "domain": "example.com",
- "attestation_full_name": "string",
- "attestation_title": "string",
- "attestation_company": "string",
- "attestation_reason_type": "PENTEST",
- "attestation_reason": "string",
- "attestation_accepted": true,
- "encryption_method": "PASSWORD_ZIP",
- "pgp_key_id": "9f9f2234-160b-42dc-be31-a99205435b67"
}{- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "domain": "string",
- "status": "PENDING",
- "encryption_method": "PASSWORD_ZIP",
- "created_at": "2019-08-24T14:15:22Z",
- "archive_password": "string",
- "password_warning": "string"
}List incident response exports for your organisation. Results are paginated. This feature is not available on standard plans and is only enabled for approved partners. Contact hello@darkstrata.io to enable this feature.
| page | integer >= 1 Default: 1 Page number |
| limit | integer [ 1 .. 100 ] Default: 20 Number of items per page |
| status | string Enum: "PENDING" "PROCESSING" "COMPLETED" "FAILED" "EXPIRED" Filter by export status |
| domain | string Filter by domain (case-insensitive contains match) |
| include_deleted | boolean Default: false Include soft-deleted exports (for audit). Their archives are gone and cannot be downloaded. |
[- {
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "domain": "string",
- "status": "PENDING",
- "encryption_method": "PASSWORD_ZIP",
- "record_count": 0,
- "file_size_bytes": 0,
- "download_count": 0,
- "expires_at": "2019-08-24T14:15:22Z",
- "created_at": "2019-08-24T14:15:22Z",
- "deleted_at": "2019-08-24T14:15:22Z",
- "requested_by": {
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "name": "string",
- "email": "string"
}
}
]Get annual usage statistics for incident response exports. This feature is not available on standard plans and is only enabled for approved partners. Contact hello@darkstrata.io to enable this feature.
{- "completed": 0,
- "used": 0,
- "deleted": 0,
- "remaining": 0,
- "limit": 0,
- "usage_percentage": 0,
- "period_start": "2019-08-24T14:15:22Z",
- "period_end": "2019-08-24T14:15:22Z"
}Get detailed information about a specific incident response export, including attestation details and download history. This feature is not available on standard plans and is only enabled for approved partners. Contact hello@darkstrata.io to enable this feature.
| id required | string <uuid> Export public ID |
{- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "domain": "string",
- "status": "PENDING",
- "encryption_method": "PASSWORD_ZIP",
- "record_count": 0,
- "file_size_bytes": 0,
- "download_count": 0,
- "last_downloaded_at": "2019-08-24T14:15:22Z",
- "expires_at": "2019-08-24T14:15:22Z",
- "error_message": "string",
- "pgp_key_fingerprint": "string",
- "has_password": true,
- "processing_started_at": "2019-08-24T14:15:22Z",
- "processing_completed_at": "2019-08-24T14:15:22Z",
- "created_at": "2019-08-24T14:15:22Z",
- "deleted_at": "2019-08-24T14:15:22Z",
- "attestation": {
- "full_name": "string",
- "title": "string",
- "company": "string",
- "reason_type": "string",
- "reason": "string",
- "ip": "string",
- "timestamp": "2019-08-24T14:15:22Z"
}, - "requested_by": {
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "name": "string",
- "email": "string"
}, - "downloads": [
- {
- "ip_address": "string",
- "user_agent": "string",
- "downloaded_at": "2019-08-24T14:15:22Z",
- "user": {
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "name": "string",
- "email": "string"
}
}
]
}Retrieve the archive password for a password-encrypted incident response export. Only available for exports using PASSWORD_ZIP or SEVEN_ZIP encryption methods. This action is audit-logged at HIGH severity. This feature is not available on standard plans and is only enabled for approved partners. Contact hello@darkstrata.io to enable this feature.
| id required | string <uuid> Export public ID |
{- "archive_password": "string"
}Returns a short-lived presigned URL for the encrypted export archive. The export must be COMPLETED and not expired. Every call is recorded against the export's download history and audit-logged at CRITICAL severity. This feature is not available on standard plans and is only enabled for approved partners. Contact hello@darkstrata.io to enable this feature.
| id required | string <uuid> Export public ID |
{- "download_url": "string"
}Soft-deletes the given exports and removes their archives from storage. Deleted exports still count towards the annual quota.
| ids required | Array of strings <uuid> [ 1 .. 100 ] items [ items <uuid > ] |
{- "ids": [
- "497f6eca-6276-4993-bfeb-53cbbbba6f08"
]
}{- "error": {
- "code": "UNAUTHORIZED",
- "message": "Invalid username or password"
}
}Immediately expires the given exports and removes their archives from storage. Use as a kill switch when an export should no longer be downloadable.
| ids required | Array of strings <uuid> [ 1 .. 100 ] items [ items <uuid > ] |
{- "ids": [
- "497f6eca-6276-4993-bfeb-53cbbbba6f08"
]
}{- "invalidated": 0
}Returns presigned URLs for each COMPLETED, unexpired export in the list. Exports that are not downloadable are skipped and counted. Downloads are recorded and audit-logged.
| ids required | Array of strings <uuid> [ 1 .. 100 ] items [ items <uuid > ] |
{- "ids": [
- "497f6eca-6276-4993-bfeb-53cbbbba6f08"
]
}{- "downloads": [
- {
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "domain": "string",
- "download_url": "string"
}
], - "skipped": 0
}List the organisation's PGP public keys. Any of these may be chosen (by id) as the encryption key when requesting a PGP-encrypted incident response export.
| id required | string <uuid> Organisation public ID |
{- "keys": [
- {
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "label": "string",
- "fingerprint": "string",
- "uploaded_at": "2019-08-24T14:15:22Z",
- "uploaded_by": {
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "name": "string",
- "email": "string"
}
}
]
}Add a PGP public key to the organisation. An organisation may hold several keys; the key to encrypt with is chosen per export via pgp_key_id. Requires organisations:write permission.
| id required | string <uuid> Organisation public ID |
| pgp_public_key required | string Armoured PGP public key (must include BEGIN/END PGP PUBLIC KEY BLOCK headers) |
| label | string <= 100 characters Optional friendly name for the key (e.g. "SOC team 2026") |
{- "pgp_public_key": "string",
- "label": "string"
}{- "message": "string",
- "key": {
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "label": "string",
- "fingerprint": "string",
- "uploaded_at": "2019-08-24T14:15:22Z",
- "uploaded_by": {
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "name": "string",
- "email": "string"
}
}
}Remove one of the organisation's PGP public keys. Past exports remain encrypted with the key they were created with.
| id required | string <uuid> Organisation public ID |
| key_id required | string <uuid> PGP key public ID |
{- "message": "string"
}Send Lens invitation emails to one or more identifiers. Creates invitation tokens valid for 7 days and sends personalised emails to each recipient.
By default, identifiers that have already completed their Lens review are skipped.
Set include_completed: true to re-invite users who have already completed.
Accepts either a single identifier ID or an array of identifier IDs for bulk sending.
| identifier_id | string <uuid> Single identifier public ID (use this OR identifier_ids, not both) |
| identifier_ids | Array of strings <uuid> [ items <uuid > ] Array of identifier public IDs for bulk sending (use this OR identifier_id, not both) |
| include_completed | boolean Default: false If true, send invitations even to identifiers that have already completed their review |
{- "identifier_id": "a400f51e-8863-4890-9fd3-3f462d124526",
- "identifier_ids": [
- "497f6eca-6276-4993-bfeb-53cbbbba6f08"
], - "include_completed": false
}{- "message": "string",
- "sent": 0,
- "skipped_completed": 0,
- "skipped_invalid": 0,
}Revoke an active lens invitation token. Only tokens that are still pending (not used, expired, or already revoked) can be revoked.
| tokenId required | string <uuid> Public ID of the lens token to revoke |
{- "message": "Token revoked successfully"
}/organisations
| page | integer >= 1 Default: 1 Page number for pagination |
| limit | integer [ 1 .. 100 ] Default: 10 Number of items per page |
| keyword | string Filter organisations by keyword |
| type | string Enum: "INDIVIDUAL" "TEAM" "MSP" "RESELLER" Filter organisations by type |
| billing_status | string Enum: "active" "trial" "trial_expired" "manual" "no_plan" "pending" "past_due" "suspended" "canceled" "expired" Filter organisations by billing status |
| activity | string Enum: "new" "engaged" "dormant" "no_login" Filter by customer activity. Buckets are mutually exclusive — |
| credential_checks | string Value: "near_limit"
|
| sort | string Default: "name" Enum: "name" "type" "created_at" "parent_organisation_name" "assets.total" "alerts.total_active" "users.last_login_at" Field to sort by. Use dot notation for nested properties. |
| direction | string Default: "asc" Enum: "asc" "desc" Sort direction (ascending or descending) |
[- {
- "id": "string",
- "name": "string",
- "type": "INDIVIDUAL",
- "breadcrumbs": [
- "string"
], - "created_at": "2019-08-24T14:15:22Z",
- "is_new": true,
- "banned_at": "2019-08-24T14:15:22Z",
- "relationship_type": "string",
- "assets": {
- "total": 0,
- "limit": 0
}, - "credential_checks": {
- "used": 0,
- "limit": 0
}, - "alerts": {
- "total_active": 0
}, - "users": {
- "total": 0,
- "last_login_at": "2019-08-24T14:15:22Z"
}, - "billing": {
- "status": "ACTIVE",
- "plan_name": "string",
- "is_manual": true,
- "extra_assets": 0,
- "customer_protection_slug": "string"
}
}
]Creates a customer organisation under a partner and puts it on a tenant plan billed to that partner. The parent must be an MSP partner.
| name required | string |
| phone | string |
| parent_organisation_id | string |
| plan_slug required | string Tenant plan, billed to the partner (GET /organisations/tenant-plans) |
| extra_assets | integer >= 0 Domains on top of the plan's, each billed at the plan's flat extra-domain price |
| customer_protection_slug | string or null Customer Protection band (a tenant-plans entry with add_on customer_protection), billed to the partner on top of the plan |
{- "name": "string",
- "phone": "string",
- "parent_organisation_id": "string",
- "plan_slug": "string",
- "extra_assets": 0,
- "customer_protection_slug": "string"
}/organisations/{id}
| id required | string Organisation ID |
| name | string |
| domain | string |
string | |
| phone | string |
| address | string |
| parentOrganisationId | string |
{- "name": "string",
- "domain": "string",
- "email": "string",
- "phone": "string",
- "address": "string",
- "parentOrganisationId": "string"
}Each plan carries the partner's price (list price less its partner discount). Use a plan's slug as plan_slug when creating a tenant or changing its plan. Customer Protection bands (customer-account monitoring) follow the plans with add_on set to customer_protection; use one's slug as customer_protection_slug.
| parent_organisation_id | string <uuid> The partner whose plans to list (defaults to the caller's organisation) |
Puts a tenant on another plan from GET /organisations/tenant-plans, billed to its partner and prorated by day.
| id required | string <uuid> Tenant organisation ID |
| plan_slug required | string |
| extra_assets | integer >= 0 Domains on top of the plan's (omitted keeps the current count) |
| customer_protection_slug | string or null Customer Protection band from GET /organisations/tenant-plans (null removes it, omitted keeps the current band) |
{- "plan_slug": "string",
- "extra_assets": 0,
- "customer_protection_slug": "string"
}{- "organisations": {
- "total": 0,
- "near_credential_check_limit": 0
}, - "assets": {
- "total": 0,
- "pending": 0,
- "failed": 0
}, - "users": {
- "total": 0,
- "active_sessions": 0
}, - "alerts": {
- "active": 0,
- "under_investigation": 0,
- "closed": 0,
- "total": 0
}
}/organisations/alerts
| page | integer >= 1 Default: 1 Page number for pagination |
| limit | integer [ 1 .. 100 ] Default: 10 Number of items per page (applies to organisations, not individual alerts) |
| status | string Enum: "ACTIVE" "UNDER_INVESTIGATION" "CLOSED" Filter by alert status |
| from_date | string <date-time> Filter alerts from this date (ISO 8601) |
| to_date | string <date-time> Filter alerts to this date (ISO 8601) |
/organisations/assets
| page | integer >= 1 Default: 1 Page number for pagination |
| limit | integer [ 1 .. 100 ] Default: 10 Number of items per page |
| keyword | string Filter assets by hostname keyword |
| status | string Enum: "VERIFIED" "UNVERIFIED" "ERROR" Filter assets by verification status |
| organisation | string Filter assets by organisation public_id |
[- {
- "id": "string",
- "hostname": "string",
- "created_at": "2019-08-24T14:15:22Z",
- "verified_at": "2019-08-24T14:15:22Z",
- "verification": {
- "status": "VERIFIED",
- "value": "string"
}, - "organisation": {
- "id": "string",
- "name": "string"
}
}
]CEF and LEEF event export for SIEM integration with IBM QRadar, ArcSight, Microsoft Sentinel, and others
Returns credential exposure events as newline-delimited CEF or LEEF formatted events for ingestion by SIEM platforms.
Supported SIEMs:
Format auto-detection:
When the format parameter is omitted, QRadar User-Agent strings default to LEEF,
all others default to CEF.
This feed carries infostealer findings. Breach findings are exported per alert by
/siem/events/{alertId}.
MITRE ATT&CK®: Each event carries the ATT&CK techniques the finding evidences, derived when the event is read. Values are comma-separated IDs; a key is left out when it would be empty.
| Meaning | CEF | LEEF |
|---|---|---|
Technique IDs, e.g. T1555.003,T1589.001 |
cs6, cs6Label=MitreTechniques |
mitreTechniques |
Tactic IDs in matrix order, e.g. TA0043,TA0006 |
flexString1, flexString1Label=MitreTactics |
mitreTactics |
Infostealer family as ATT&CK Software ID, e.g. S1240 |
flexString2, flexString2Label=MalwareFamily |
malwareFamily |
Finding class. The CEF Device Event Class ID is credential-exposure:<class>:
stealer-fresh (VERIFIED_FRESH), stealer-reuse (PASSWORD_REUSE_CONFIRMED),
combolist (POSSIBLE_COMBOLIST), breach (breach finding) or stealer (provenance not yet
known, or INSUFFICIENT_DATA). LEEF events use the event ID CredentialExposure.
Other fields.
CEF: suser (identifier), cs1 ServiceURL ([redacted] for an OUTBOUND service that is not one
of your monitored assets), cat source (MALWARE or BREACH), cs2 Flow
(INBOUND or OUTBOUND), cs3 CredentialType, cn1 ThreatScore (1-5), rt, externalId
(finding ID), cs4 AlertID (per-alert export), dhost (monitored asset), cs5 PasswordStrength.
LEEF: cat=credential-exposure, sev, sourceType (MALWARE or BREACH), usrName, url,
devTime with devTimeFormat, flowDirection, externalId, credentialType, threatScore,
alertId, assetHostname, passwordStrength. Severity (0-10) is the threat score doubled, or 5 when unknown.
Incremental sync.
Events come back oldest first. Store the X-Next-Cursor response header and pass
it as cursor on the next request; repeat while X-Has-More is true, then poll
on your normal schedule. Every event is delivered exactly once, however many arrive
between polls. Omit cursor on the first request to start from the beginning, or
add since to start from a date. The newest minute of events is held back until
it settles.
| format | string Enum: "cef" "leef" Output format. Auto-detected from User-Agent when omitted. QRadar clients default to LEEF, others default to CEF. |
| since | string <date-time> ISO 8601 start date. Only events from this time are returned; use it on the first request, then follow the cursor. |
| hash_emails | boolean Default: false Hash email addresses with SHA-256 for privacy |
| confidence_threshold | integer [ 0 .. 100 ] Default: 0 Minimum confidence score for events |
| cursor | string <= 128 characters Opaque cursor: the |
| limit | integer [ 1 .. 500 ] Default: 100 Events per response (max 500) |
CEF:0|DarkStrata|DarkStrata|1.0|credential-exposure:stealer-fresh|Compromised credential: j.smith@example.com on [redacted]|8|suser=j.smith@example.com cs1=[redacted] cs1Label=ServiceURL cat=MALWARE cs2=OUTBOUND cs2Label=Flow cs3=EP cs3Label=CredentialType cn1=4 cn1Label=ThreatScore rt=Oct 18 2026 02:14:00 UTC externalId=3f2b7c1d-9a4e-4b6f-8d21-5c0e7a9b1f34 dhost=example.com cs5=weak cs5Label=PasswordStrength cs6=T1555.003,T1589.001,T1539 cs6Label=MitreTechniques flexString1=TA0043,TA0006 flexString1Label=MitreTactics flexString2=S1240 flexString2Label=MalwareFamily
Returns credential exposure events for a single alert as newline-delimited
CEF or LEEF formatted events.
Infostealer and breach findings are both included: breach findings carry cat=BREACH
(CEF, Device Event Class ID credential-exposure:breach) or sourceType=BREACH (LEEF).
Every event carries the alert ID (CEF cs4, cs4Label=AlertID; LEEF alertId) and the
same MITRE ATT&CK® and other fields as /siem/events.
| alertId required | string <uuid> Alert public ID |
| format | string Enum: "cef" "leef" Output format. Auto-detected from User-Agent when omitted. |
| hash_emails | boolean Default: false Hash email addresses for privacy |
| confidence_threshold | integer [ 0 .. 100 ] Default: 0 Minimum confidence score |
CEF:0|DarkStrata|DarkStrata|1.0|credential-exposure:stealer-fresh|Compromised credential: j.smith@example.com on [redacted]|8|suser=j.smith@example.com cs1=[redacted] cs1Label=ServiceURL cat=MALWARE cs2=OUTBOUND cs2Label=Flow cs3=EP cs3Label=CredentialType cn1=4 cn1Label=ThreatScore rt=Oct 18 2026 02:14:00 UTC externalId=3f2b7c1d-9a4e-4b6f-8d21-5c0e7a9b1f34 cs4=550e8400-e29b-41d4-a716-446655440000 cs4Label=AlertID dhost=example.com cs5=weak cs5Label=PasswordStrength cs6=T1555.003,T1589.001,T1539 cs6Label=MitreTechniques flexString1=TA0043,TA0006 flexString1Label=MitreTactics flexString2=S1240 flexString2Label=MalwareFamily CEF:0|DarkStrata|DarkStrata|1.0|credential-exposure:breach|Compromised credential: a.jones@example.com on linkedin.com|6|suser=a.jones@example.com cs1=linkedin.com cs1Label=ServiceURL cat=BREACH cs2=OUTBOUND cs2Label=Flow cs3=EP cs3Label=CredentialType cn1=3 cn1Label=ThreatScore rt=Oct 18 2026 09:30:12 UTC externalId=8c4d2e6f-1b3a-4c5d-9e7f-0a1b2c3d4e5f cs4=550e8400-e29b-41d4-a716-446655440000 cs4Label=AlertID dhost=example.com cs6=T1589.001 cs6Label=MitreTechniques flexString1=TA0043 flexString1Label=MitreTactics
STIX 2.1 threat intelligence export for alerts and indicators, with Splunk ES and IBM QRadar compatibility
Returns credential exposure alerts as STIX 2.1 bundles suitable for SIEM integration.
Each alert is converted to a STIX Report containing Indicators and Identities
representing the compromised credentials and related threat intel. Infostealer and
breach findings both export (source: BREACH in the extension, label source:breach).
STIX Object Types Returned (in this order):
report - The alert container with summary metadata (objects[0]; left out when no finding exports)extension-definition - DarkStrata custom extension schema (objects[1])indicator - Individual compromised credentials (or observed-data plus its
user-account and domain-name objects in Splunk mode)identity - Compromised user identities (optional, include=identities)relationship - Links between indicators and identitiesMITRE ATT&CK®. ATT&CK tags are derived for each finding when the bundle is built:
kill_chain_phases (kill_chain_name: mitre-attack, phase_name the tactic
shortname, e.g. credential-access) for the techniques' tactics, and one external_references
entry per technique (source_name: mitre-attack, external_id e.g. T1555.003, url on attack.mitre.org).x_darkstrata_credential extension (version 1.1.0, schema at
https://api.darkstrata.io/v1/stix/extensions/credential-exposure/v1) carries mitre
(techniques with basis observed or inferred, and the infostealer family's ATT&CK Software ID)
and provenance (VERIFIED_FRESH, PASSWORD_REUSE_CONFIRMED, POSSIBLE_COMBOLIST or INSUFFICIENT_DATA;
infostealer findings only).source:*, flow:*, severity-*) plus
one mitre:<technique id> label per technique, e.g. mitre:T1555.003.Splunk Compatibility:
Set format=splunk to receive Splunk ES compatible observed-data objects instead of
indicator patterns. Splunk ES only parses observed-data, not indicator patterns.
Incremental Sync:
Use the since parameter for incremental fetches. Store the last sync timestamp
and pass it to retrieve only new/modified alerts since that time.
| since | string <date-time> Example: since=2025-01-01T00:00:00Z ISO 8601 timestamp for incremental fetch |
| detail | string Default: "full" Enum: "summary" "full" Level of detail in STIX output |
| include | string Example: include=identities Comma-separated includes (identities) |
| format | string Default: "stix21" Enum: "stix21" "splunk" Output format. Auto-detected from User-Agent header when Splunk is detected. Explicit value takes precedence over auto-detection. |
| hash_emails | boolean Default: false Hash email addresses for privacy. Identities and Splunk observed-data use
|
| confidence_threshold | integer [ 0 .. 100 ] Default: 0 Minimum confidence score for indicators |
| page | integer >= 1 Default: 1 Page number |
| limit | integer [ 1 .. 100 ] Default: 10 Alerts per page (max 100) |
[- {
- "type": "bundle",
- "id": "bundle--f9b2fd53-4335-4b51-a84c-0e1f2a3b4c5d",
- "objects": [
- {
- "type": "report",
- "spec_version": "2.1",
- "id": "report--550e8400-e29b-41d4-a716-446655440000",
- "created": "2026-10-19T06:00:03.000Z",
- "modified": "2026-10-19T06:00:03.000Z",
- "name": "Credential Exposure: 1 Customer",
- "description": "DarkStrata detected 1 compromised credential affecting 1 unique identifier across 1 corporate asset. Sources: MALWARE: 1. Credential types: EP: 1. Affected assets: example.com. Detection period: 2026-10-18T00:00:00.000Z to 2026-10-19T00:00:00.000Z.",
- "report_types": [
- "threat-report"
], - "published": "2026-10-19T06:00:03.000Z",
- "object_refs": [
- "indicator--3f2b7c1d-9a4e-4b6f-8d21-5c0e7a9b1f34"
], - "labels": [
- "darkstrata",
- "credential-exposure",
- "source:malware"
], - "external_references": [
- {
- "source_name": "DarkStrata",
- "external_id": "550e8400-e29b-41d4-a716-446655440000",
}
]
}, - {
- "type": "extension-definition",
- "spec_version": "2.1",
- "id": "extension-definition--d6132570-7659-4922-9fc4-420e4f8cba63",
- "created": "2025-01-01T00:00:00.000Z",
- "modified": "2026-10-19T00:00:00.000Z",
- "name": "DarkStrata Credential Exposure Extension",
- "version": "1.1.0",
- "extension_types": [
- "property-extension"
]
}, - {
- "type": "indicator",
- "spec_version": "2.1",
- "id": "indicator--3f2b7c1d-9a4e-4b6f-8d21-5c0e7a9b1f34",
- "created": "2026-10-18T02:14:00.000Z",
- "modified": "2026-10-18T02:14:00.000Z",
- "description": "Email/password pair exposed via infostealer malware for example.com. Credential was used on a corporate asset (inbound exposure). Password strength: weak.",
- "indicator_types": [
- "compromised"
], - "pattern_type": "stix",
- "valid_from": "2026-10-18T02:14:00.000Z",
- "confidence": 80,
- "labels": [
- "darkstrata",
- "credential-exposure",
- "source:malware",
- "flow:inbound",
- "severity-high"
], - "external_references": [
- {
- "source_name": "DarkStrata",
- "external_id": "550e8400-e29b-41d4-a716-446655440000",
}, - {
- "source_name": "mitre-attack",
- "external_id": "T1555.003",
}, - {
- "source_name": "mitre-attack",
- "external_id": "T1589.001",
}, - {
- "source_name": "mitre-attack",
- "external_id": "T1539",
}
], - "kill_chain_phases": [
- {
- "kill_chain_name": "mitre-attack",
- "phase_name": "reconnaissance"
}, - {
- "kill_chain_name": "mitre-attack",
- "phase_name": "credential-access"
}
], - "extensions": {
- "extension-definition--d6132570-7659-4922-9fc4-420e4f8cba63": {
- "extension_type": "property-extension",
- "x_darkstrata_credential": {
- "source": "MALWARE",
- "flow": "INBOUND",
- "threat_score": 4,
- "password_strength": "weak",
- "discovered_at": "2026-10-18T02:14:00.000Z",
- "credential_type": "EP",
- "alert_id": "550e8400-e29b-41d4-a716-446655440000",
- "asset_hostname": "example.com",
- "provenance": "VERIFIED_FRESH",
- "mitre": {
- "attack_version": "20.0",
- "domain": "enterprise-attack",
- "techniques": [
- {
- "id": "T1555.003",
- "name": "Credentials from Web Browsers",
- "parent_name": "Credentials from Password Stores",
- "tactic_ids": [
- "TA0006"
], - "basis": "observed"
}, - {
- "id": "T1589.001",
- "name": "Credentials",
- "parent_name": "Gather Victim Identity Information",
- "tactic_ids": [
- "TA0043"
], - "basis": "observed"
}, - {
- "id": "T1539",
- "name": "Steal Web Session Cookie",
- "tactic_ids": [
- "TA0006"
], - "basis": "observed"
}
], - "software": [
- {
- "id": "S1240",
- "name": "RedLine Stealer",
- "basis": "observed"
}
]
}
}
}
}
}
]
}
]Returns a single credential exposure alert as a complete STIX 2.1 bundle. Useful for fetching detailed threat intelligence for a specific alert.
The bundle includes the alert as a STIX Report (objects[0]), the extension definition
(objects[1]) and all associated indicators, identities, and relationships. Infostealer
and breach findings both export.
Indicators carry MITRE ATT&CK® kill_chain_phases, external_references and the
extension's mitre and provenance; Splunk-format observed-data carries
mitre:<technique id> and severity-* labels. See GET /stix/alerts for details.
| id required | string <uuid> Example: 550e8400-e29b-41d4-a716-446655440000 Alert public ID |
| detail | string Default: "full" Enum: "summary" "full" Level of detail in STIX output |
| include | string Comma-separated includes (identities) |
| format | string Default: "stix21" Enum: "stix21" "splunk" Output format. Auto-detected from User-Agent header when Splunk is detected. Explicit value takes precedence over auto-detection. |
| hash_emails | boolean Default: false Hash email addresses for privacy |
| confidence_threshold | integer [ 0 .. 100 ] Default: 0 Minimum confidence score |
{- "type": "bundle",
- "id": "bundle--f9b2fd53-4335-4b51-a84c-0e1f2a3b4c5d",
- "objects": [
- {
- "type": "report",
- "spec_version": "2.1",
- "id": "report--550e8400-e29b-41d4-a716-446655440000",
- "created": "2026-10-19T06:00:03.000Z",
- "modified": "2026-10-19T06:00:03.000Z",
- "name": "Credential Exposure: 1 Customer",
- "description": "DarkStrata detected 1 compromised credential affecting 1 unique identifier across 1 corporate asset. Sources: MALWARE: 1. Credential types: EP: 1. Affected assets: example.com. Detection period: 2026-10-18T00:00:00.000Z to 2026-10-19T00:00:00.000Z.",
- "report_types": [
- "threat-report"
], - "published": "2026-10-19T06:00:03.000Z",
- "object_refs": [
- "indicator--3f2b7c1d-9a4e-4b6f-8d21-5c0e7a9b1f34"
], - "labels": [
- "darkstrata",
- "credential-exposure",
- "source:malware"
], - "external_references": [
- {
- "source_name": "DarkStrata",
- "external_id": "550e8400-e29b-41d4-a716-446655440000",
}
]
}, - {
- "type": "extension-definition",
- "spec_version": "2.1",
- "id": "extension-definition--d6132570-7659-4922-9fc4-420e4f8cba63",
- "created": "2025-01-01T00:00:00.000Z",
- "modified": "2026-10-19T00:00:00.000Z",
- "name": "DarkStrata Credential Exposure Extension",
- "version": "1.1.0",
- "extension_types": [
- "property-extension"
]
}, - {
- "type": "indicator",
- "spec_version": "2.1",
- "id": "indicator--3f2b7c1d-9a4e-4b6f-8d21-5c0e7a9b1f34",
- "created": "2026-10-18T02:14:00.000Z",
- "modified": "2026-10-18T02:14:00.000Z",
- "description": "Email/password pair exposed via infostealer malware for example.com. Credential was used on a corporate asset (inbound exposure). Password strength: weak.",
- "indicator_types": [
- "compromised"
], - "pattern_type": "stix",
- "valid_from": "2026-10-18T02:14:00.000Z",
- "confidence": 80,
- "labels": [
- "darkstrata",
- "credential-exposure",
- "source:malware",
- "flow:inbound",
- "severity-high"
], - "external_references": [
- {
- "source_name": "DarkStrata",
- "external_id": "550e8400-e29b-41d4-a716-446655440000",
}, - {
- "source_name": "mitre-attack",
- "external_id": "T1555.003",
}, - {
- "source_name": "mitre-attack",
- "external_id": "T1589.001",
}, - {
- "source_name": "mitre-attack",
- "external_id": "T1539",
}
], - "kill_chain_phases": [
- {
- "kill_chain_name": "mitre-attack",
- "phase_name": "reconnaissance"
}, - {
- "kill_chain_name": "mitre-attack",
- "phase_name": "credential-access"
}
], - "extensions": {
- "extension-definition--d6132570-7659-4922-9fc4-420e4f8cba63": {
- "extension_type": "property-extension",
- "x_darkstrata_credential": {
- "source": "MALWARE",
- "flow": "INBOUND",
- "threat_score": 4,
- "password_strength": "weak",
- "discovered_at": "2026-10-18T02:14:00.000Z",
- "credential_type": "EP",
- "alert_id": "550e8400-e29b-41d4-a716-446655440000",
- "asset_hostname": "example.com",
- "provenance": "VERIFIED_FRESH",
- "mitre": {
- "attack_version": "20.0",
- "domain": "enterprise-attack",
- "techniques": [
- {
- "id": "T1555.003",
- "name": "Credentials from Web Browsers",
- "parent_name": "Credentials from Password Stores",
- "tactic_ids": [
- "TA0006"
], - "basis": "observed"
}, - {
- "id": "T1589.001",
- "name": "Credentials",
- "parent_name": "Gather Victim Identity Information",
- "tactic_ids": [
- "TA0043"
], - "basis": "observed"
}, - {
- "id": "T1539",
- "name": "Steal Web Session Cookie",
- "tactic_ids": [
- "TA0006"
], - "basis": "observed"
}
], - "software": [
- {
- "id": "S1240",
- "name": "RedLine Stealer",
- "basis": "observed"
}
]
}
}
}
}
}
]
}Returns infostealer credential findings as STIX Indicators (or observed-data in Splunk mode).
This endpoint provides a flat list of all indicators without the alert grouping,
useful for bulk import into threat intelligence platforms. The bundle starts with the
extension definition. Breach findings are exported per alert by /stix/alerts.
Incremental sync.
Pass cursor (empty on the first request) to page by cursor instead of by page
number: indicators come back oldest first, store the X-Next-Cursor response
header and pass it back as cursor, repeating while X-Has-More is true. Every
indicator is delivered exactly once. since still sets the start date and page
is ignored. The newest minute is held back until it settles. Without cursor the
endpoint keeps its page-number behaviour (newest first).
DarkStrata Extension:
Each indicator includes the extension-definition--d6132570-7659-4922-9fc4-420e4f8cba63
extension with additional metadata:
source: MALWARE or BREACHflow: INBOUND or OUTBOUNDservice_url: The service where credentials were exposedthreat_score: Severity level (1-5)password_strength: weak/medium/strongcredential_type: EP (email/password) or UP (username/password)provenance: infostealer provenance label (VERIFIED_FRESH, PASSWORD_REUSE_CONFIRMED, POSSIBLE_COMBOLIST, INSUFFICIENT_DATA)mitre: MITRE ATT&CK® techniques (each observed or inferred) and the infostealer family's ATT&CK Software IDMITRE ATT&CK®. ATT&CK tags are derived for each finding when the bundle is built:
kill_chain_phases (kill_chain_name: mitre-attack, phase_name the tactic
shortname, e.g. credential-access) for the techniques' tactics, and one external_references
entry per technique (source_name: mitre-attack, external_id e.g. T1555.003, url on attack.mitre.org).x_darkstrata_credential extension (version 1.1.0, schema at
https://api.darkstrata.io/v1/stix/extensions/credential-exposure/v1) carries mitre
(techniques with basis observed or inferred, and the infostealer family's ATT&CK Software ID)
and provenance (VERIFIED_FRESH, PASSWORD_REUSE_CONFIRMED, POSSIBLE_COMBOLIST or INSUFFICIENT_DATA;
infostealer findings only).source:*, flow:*, severity-*) plus
one mitre:<technique id> label per technique, e.g. mitre:T1555.003.Confidence Mapping: DarkStrata threat scores are mapped to STIX confidence:
| since | string <date-time> ISO 8601 timestamp for incremental fetch |
| format | string Default: "stix21" Enum: "stix21" "splunk" Output format. Auto-detected from User-Agent header when Splunk is detected. Explicit value takes precedence over auto-detection. |
| hash_emails | boolean Default: false Hash email addresses for privacy. Splunk observed-data uses |
| confidence_threshold | integer [ 0 .. 100 ] Default: 0 Minimum confidence score to include |
| page | integer >= 1 Default: 1 Page number (ignored when |
| cursor | string <= 128 characters Opaque cursor: the |
| limit | integer [ 1 .. 500 ] Default: 100 Indicators per page (max 500) |
{- "type": "bundle",
- "id": "bundle--6e5d4c3b-2a19-4f08-b7e6-d5c4b3a29180",
- "objects": [
- {
- "type": "extension-definition",
- "spec_version": "2.1",
- "id": "extension-definition--d6132570-7659-4922-9fc4-420e4f8cba63",
- "created": "2025-01-01T00:00:00.000Z",
- "modified": "2026-10-19T00:00:00.000Z",
- "name": "DarkStrata Credential Exposure Extension",
- "version": "1.1.0",
- "extension_types": [
- "property-extension"
]
}, - {
- "type": "indicator",
- "spec_version": "2.1",
- "id": "indicator--3f2b7c1d-9a4e-4b6f-8d21-5c0e7a9b1f34",
- "created": "2026-10-18T02:14:00.000Z",
- "modified": "2026-10-18T02:14:00.000Z",
- "description": "Email/password pair exposed via infostealer malware for example.com. Credential was used on a corporate asset (inbound exposure). Password strength: weak.",
- "indicator_types": [
- "compromised"
], - "pattern_type": "stix",
- "valid_from": "2026-10-18T02:14:00.000Z",
- "confidence": 80,
- "labels": [
- "darkstrata",
- "credential-exposure",
- "source:malware",
- "flow:inbound",
- "severity-high"
], - "external_references": [
- {
- "source_name": "mitre-attack",
- "external_id": "T1555.003",
}, - {
- "source_name": "mitre-attack",
- "external_id": "T1589.001",
}, - {
- "source_name": "mitre-attack",
- "external_id": "T1539",
}
], - "kill_chain_phases": [
- {
- "kill_chain_name": "mitre-attack",
- "phase_name": "reconnaissance"
}, - {
- "kill_chain_name": "mitre-attack",
- "phase_name": "credential-access"
}
], - "extensions": {
- "extension-definition--d6132570-7659-4922-9fc4-420e4f8cba63": {
- "extension_type": "property-extension",
- "x_darkstrata_credential": {
- "source": "MALWARE",
- "flow": "INBOUND",
- "threat_score": 4,
- "password_strength": "weak",
- "discovered_at": "2026-10-18T02:14:00.000Z",
- "credential_type": "EP",
- "asset_hostname": "example.com",
- "provenance": "VERIFIED_FRESH",
- "mitre": {
- "attack_version": "20.0",
- "domain": "enterprise-attack",
- "techniques": [
- {
- "id": "T1555.003",
- "name": "Credentials from Web Browsers",
- "parent_name": "Credentials from Password Stores",
- "tactic_ids": [
- "TA0006"
], - "basis": "observed"
}, - {
- "id": "T1589.001",
- "name": "Credentials",
- "parent_name": "Gather Victim Identity Information",
- "tactic_ids": [
- "TA0043"
], - "basis": "observed"
}, - {
- "id": "T1539",
- "name": "Steal Web Session Cookie",
- "tactic_ids": [
- "TA0006"
], - "basis": "observed"
}
], - "software": [
- {
- "id": "S1240",
- "name": "RedLine Stealer",
- "basis": "observed"
}
]
}
}
}
}
}
]
}Returns API usage statistics for the current organisation. Can filter by specific API key, date range, and granularity.
| kid | string Filter by specific API key (kid) |
| start_date | string <date> Start date for the query range (YYYY-MM-DD) |
| end_date | string <date> End date for the query range (YYYY-MM-DD) |
| granularity | string Default: "daily" Enum: "hourly" "daily" Data granularity (hourly or daily) |
[- {
- "kid": "string",
- "hour_bucket": "2019-08-24T14:15:22Z",
- "day_bucket": "2019-08-24T14:15:22Z",
- "source": "main_api",
- "call_count": 0
}
]Returns a summary of API usage for the current billing period. Useful for displaying usage against plan limits.
{- "api_keys_used": 0,
- "total_calls": 0,
- "first_call": "2019-08-24T14:15:22Z",
- "last_call": "2019-08-24T14:15:22Z",
- "period_start": "2019-08-24T14:15:22Z"
}Returns API usage grouped by API key for the current billing period. Shows which API keys are generating the most traffic.
[- {
- "kid": "string",
- "key_name": "string",
- "total_calls": 0,
- "main_api_calls": 0,
- "kanon_calls": 0
}
]/users
| page | integer >= 1 Default: 1 Page number |
| limit | integer [ 1 .. 100 ] Default: 10 Number of items per page |
| search | string Keyword filter applied to names and identifiers |
| role | string Filter by user role |
| verify_status | string Enum: "UNVERIFIED" "VERIFIED" "PENDING_REVIEW" "SUSPENDED" Filter by user verification status. If not provided, all users are returned. Use PENDING_REVIEW to show users awaiting approval, VERIFIED for approved users, UNVERIFIED for new unverified users, or SUSPENDED for suspended accounts. |
| sort | string Default: "email" Field to sort by |
| direction | string Default: "asc" Enum: "asc" "desc" Sort direction |
[- {
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "email": "string",
- "name": "string",
- "created_at": "2019-08-24T14:15:22Z",
- "last_login_at": "2019-08-24T14:15:22Z",
- "is_enabled": true,
- "verify_status": "string",
- "role": {
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "name": "string"
}
}
]/users/invite
| email required | string <email> Email address of the user to invite |
| role_id required | string Role ID to assign to the invited user |
{- "role_id": "string"
}{- "message": "string",
- "invitation_id": "string"
}/users/invitations
| page | integer >= 1 Default: 1 Page number |
| limit | integer [ 1 .. 100 ] Default: 10 Number of items per page |
| status | string Enum: "pending" "expired" "accepted" "revoked" Filter by invitation status |
[- {
- "public_id": "string",
- "email": "string",
- "role_name": "string",
- "invited_by_name": "string",
- "invited_by_email": "string",
- "created_at": "2019-08-24T14:15:22Z",
- "expires_at": "2019-08-24T14:15:22Z",
- "accepted_at": "2019-08-24T14:15:22Z",
- "revoked_at": "2019-08-24T14:15:22Z",
- "status": "pending"
}
]Suspends a user account, preventing them from logging in. Suspended users cannot re-register.
| id required | string User ID |
| reason | string Reason for suspension |
{- "reason": "string"
}Returns the catalogue of event keys (e.g. alert.stealer_log.created) that webhooks can subscribe to. Alert events carry MITRE ATT&CK® tags in data.alert.mitre; the delivery body is described under PUT /webhooks (WebhookAlertDelivery).
| page | string Page number (default 1) |
| limit | string Results per page (default 50) |
| namespace | string Filter by event namespace (e.g. ALERT, ASSET, API_KEY) |
| keyword | string Filter by event key, title, or description |
[- {
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "event_key": "alert.stealer_log.created",
- "event_name": "string",
- "namespace": "string",
- "severity": "string",
- "title": "string",
- "description": "string"
}
]Returns the organisation's webhooks with status and last delivery result.
| page | string Page number (default 1) |
| limit | string Results per page (default 10) |
| keyword | string Filter by name or description |
[- {
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "url": "string",
- "name": "string",
- "description": "string",
- "integration_type": "string",
- "is_enabled": true,
- "include_child_organisations": true,
- "events_count": 0,
- "created_at": "2019-08-24T14:15:22Z"
}
]Registers a webhook that receives subscribed events by HTTP push. Event keys come from GET /webhooks/events.
Delivery payload. A GENERIC webhook receives a JSON envelope (event, event_id, occurred_at,
data, timestamp, webhook_public_id, organisation). For the alert events
alert.stealer_log.created, alert.breach_exposure.created, alert.lens.password_use_confirmed,
alert.lens.supplier_password_use_confirmed and vip.alert.created, data.alert.mitre carries the
MITRE ATT&CK® techniques and infostealer software the finding evidences, each with a basis of
observed or inferred. The full body is the WebhookAlertDelivery schema, shown under this
operation's alertDelivery callback. DATTO, CONNECTWISE, AUTOTASK and STIX_2_1 currently receive
the same JSON envelope as GENERIC; a Slack incoming-webhook URL receives a Slack message; the
ticketing types (SERVICE_NOW, JIRA, ZENDESK, FRESHDESK) open a ticket built from the envelope; a
custom payload template replaces the envelope. To verify deliveries, see
Webhook signatures.
| url required | string Endpoint URL to deliver events to |
| name required | string |
| description | string |
| events | Array of strings Event keys to subscribe to |
| integration_type | string Enum: "GENERIC" "SLACK" "SERVICE_NOW" "JIRA" "ZENDESK" "FRESHDESK" "DATTO" "CONNECTWISE" "AUTOTASK" "STIX_2_1" |
| content_type | string |
| is_enabled | boolean Default: true |
| retryCount | integer Default: 3 |
| timeout | integer Default: 30000 Delivery timeout in milliseconds |
| include_child_organisations | boolean Default: false Also deliver events from every client organisation below this one (MSP partners only; needs a plan with msp). Each delivery then carries source_organisation (id, name, is_client, depth, path from this organisation down to the source) naming exactly which client the event came from. |
Array of objects | |
object |
{- "url": "string",
- "name": "string",
- "description": "string",
- "events": [
- "string"
], - "integration_type": "GENERIC",
- "content_type": "string",
- "is_enabled": true,
- "retryCount": 3,
- "timeout": 30000,
- "include_child_organisations": false,
- "headers": [
- {
- "key": "string",
- "value": "string",
- "is_secret": true
}
], - "authentication": {
- "type": "none",
- "username": "string",
- "password": "string",
- "bearerToken": "string",
- "apiKey": "string",
- "value": "string"
}
}{- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
}{- "event": "alert.stealer_log.created",
- "event_id": "0b9f6c1e-2d3a-4f5b-8c7d-9e0f1a2b3c4d",
- "occurred_at": "2026-10-19T06:00:04.112Z",
- "data": {
- "alert": {
- "id": "550e8400-e29b-41d4-a716-446655440000",
- "class": "CREDENTIAL_EXPOSURE",
- "detection_class": "STEALER_LOG_FRESH",
- "severity": "HIGH",
- "alert_severity": "HIGH",
- "title": "Credential Exposure: 3 Staff Accounts",
- "description": "3 staff accounts (3 with active malware) exposed across 1 asset.",
- "mitre": {
- "attack_version": "20.0",
- "domain": "enterprise-attack",
- "techniques": [
- {
- "id": "T1555.003",
- "name": "Credentials from Web Browsers",
- "parent_name": "Credentials from Password Stores",
- "tactic_ids": [
- "TA0006"
], - "basis": "observed"
}, - {
- "id": "T1589.001",
- "name": "Credentials",
- "parent_name": "Gather Victim Identity Information",
- "tactic_ids": [
- "TA0043"
], - "basis": "observed"
}, - {
- "id": "T1539",
- "name": "Steal Web Session Cookie",
- "tactic_ids": [
- "TA0006"
], - "basis": "observed"
}
], - "software": [
- {
- "id": "S1240",
- "name": "RedLine Stealer",
- "basis": "observed"
}
]
}
}, - "summary": {
- "total_matches": 4,
- "unique_identifiers": 3,
- "unique_assets": 1,
- "first_seen": "2026-10-18T02:14:00.000Z",
- "last_seen": "2026-10-18T21:40:00.000Z"
}, - "audience": {
- "staff": 3,
- "staff_critical": 0,
- "staff_infected": 3,
- "staff_breached": 0,
- "customers": 0
}, - "affected_domains": [
- {
- "hostname": "example.com",
- "staff_count": 3,
- "customer_count": 0
}
], - "period": {
- "from": "2026-10-18T00:00:00.000Z",
- "to": "2026-10-19T00:00:00.000Z"
}, - "timestamp": "2026-10-19T06:00:04.090Z"
}, - "timestamp": "2026-10-19T06:00:04.130Z",
- "webhook_id": 42,
- "webhook_public_id": "7c1d2e3f-4a5b-4c6d-8e7f-901a2b3c4d5e",
- "organisation": {
- "id": "2f6e8a10-3b4c-4d5e-9f60-718293a4b5c6",
- "name": "Example Ltd"
}
}Validates connection details for a service-desk integration (ServiceNow, Zendesk, Jira, Freshdesk) without creating a webhook.
| integration_type required | string Enum: "SERVICE_NOW" "ZENDESK" "JIRA" "FRESHDESK" |
required | object |
{- "integration_type": "SERVICE_NOW",
- "serviceDeskConfig": {
- "instance_url": "company.zendesk.com",
- "credentials": { },
- "project_or_queue_id": "string"
}
}{- "success": true,
- "message": "string",
- "error": "string"
}Returns URL, headers, authentication, subscribed events, and delivery settings. Secret values are returned decrypted for editing.
| id required | string <uuid> Webhook ID |
{- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "url": "string",
- "name": "string",
- "description": "string",
- "events": [
- "string"
], - "is_enabled": true,
- "include_child_organisations": true,
- "retry_count": 0,
- "timeout": 0,
- "integration_type": "string"
}Full replace of the webhook's configuration — omitted optional fields reset to defaults (e.g. omitting authentication clears it). Fetch the current config first and send the complete desired state. Body shape matches PUT /webhooks.
| id required | string <uuid> Webhook ID |
| url required | string |
| name required | string |
| description | string |
| events | Array of strings |
| integration_type | string |
| is_enabled | boolean |
| retryCount | integer |
| timeout | integer |
| include_child_organisations | boolean Also deliver events from every client organisation below this one (MSP partners only; needs a plan with msp). Each delivery then carries source_organisation (id, name, is_client, depth, path from this organisation down to the source) naming exactly which client the event came from. Unlike the other fields, omitting it keeps the current value. |
{- "url": "string",
- "name": "string",
- "description": "string",
- "events": [
- "string"
], - "integration_type": "string",
- "is_enabled": true,
- "retryCount": 0,
- "timeout": 0,
- "include_child_organisations": true
}{- "error": {
- "code": "UNAUTHORIZED",
- "message": "Invalid username or password"
}
}Permanently deletes a webhook and its event subscriptions. This action cannot be undone.
| id required | string <uuid> Webhook ID |
{- "error": {
- "code": "UNAUTHORIZED",
- "message": "Invalid username or password"
}
}One entry per delivery (newest first), updated in place as it is retried. Failed and retrying deliveries carry the HTTP status and error. Retries back off from 1 minute to 24 hours; 4xx responses other than 408, 425 and 429 are not retried.
| id required | string <uuid> Webhook ID |
| page | integer >= 1 Default: 1 |
| limit | integer [ 1 .. 100 ] Default: 20 |
| status | string Enum: "SUCCESS" "FAILED" "RETRYING" "PENDING" Only deliveries in this state |
[- {
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "event_key": "string",
- "event_title": "string",
- "status": "SUCCESS",
- "response_status": 0,
- "error_message": "string",
- "response_body": "string",
- "payload": "string",
- "attempts": 0,
- "execution_time_ms": 0,
- "source_organisation": {
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "name": "string"
}, - "created_at": "2019-08-24T14:15:22Z",
- "updated_at": "2019-08-24T14:15:22Z"
}
]Dispatches a test delivery so you can verify the endpoint receives events.
| id required | string <uuid> Webhook ID |
| event | string Event key to simulate (default: webhook.test) |
| payload | object Custom test payload |
{- "event": "string",
- "payload": { }
}{- "success": true,
- "message": "string",
- "jobId": "string"
}