Skip to content

Add credentials global search api #142

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
mariano-martin1 wants to merge 4 commits into from
Closed

Add credentials global search api #142

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
d2eafd2
create global search API group
Nov 3, 2025
82031b9
change title to current search events endpoint
Nov 3, 2025
f66c522
add search credentials api doc
Nov 3, 2025
0d8f0d7
create credentials search api snippet for description
Nov 3, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
160 changes: 4 additions & 156 deletions docs/api-reference/astp/endpoints/post-credentials-search.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,167 +5,15 @@ authMethod: "bearer"
---

import GatedAccessFeatureAstp from '/snippets/gated-access-feature-astp.mdx';
import CrendentialSearchCommon from '/snippets/endpoint-credential-search-common.mdx';
import CrendentialSearchDescription from '/snippets/endpoint-credential-search-description.mdx';

<GatedAccessFeatureAstp />

Returns a list of credentials matching the query provided.

<ResponseExample>

```json Response Example
{
"items": [
{
"domain": "scatterholt.com",
"hash": "B@dPassw0rd",
"hash_type": null,
"id": 33880703907,
"identity_name": "[email protected]",
"imported_at": "2024-07-22T19:25:52.893439+00:00",
"known_password_id": null,
"source": {
"breached_at": null,
"description_en": "Collection of multiple combo lists (emails and passwords) exchanged on illicit networks.",
"description_fr": "Collection de multiples listes \"combos\" (adresses courriel et mots de passe) \u00e9chang\u00e9es sur des r\u00e9seaux illicites.",
"id": "combolists",
"is_alert_enabled": true,
"leaked_at": null,
"name": "Combolists"
},
"source_id": "combolists"
},
{
"domain": "scatterholt.com",
"hash": "1qaz2wsx",
"hash_type": "unknown",
"id": 33880703906,
"identity_name": "[email protected]",
"imported_at": "2024-07-22T19:25:52.893439+00:00",
"known_password_id": null,
"source": {
"breached_at": null,
"description_en": "Collection of multiple combo lists (emails and passwords) exchanged on illicit networks.",
"description_fr": "Collection de multiples listes \"combos\" (adresses courriel et mots de passe) \u00e9chang\u00e9es sur des r\u00e9seaux illicites.",
"id": "combolists",
"is_alert_enabled": true,
"leaked_at": null,
"name": "Combolists"
},
"source_id": "combolists"
}
],
"next": "WyJjb20uc2NhdHRlcmhvbHQiLCAxNjczNjg4ODg4NV0"
}
```

</ResponseExample>

## Paging

This endpoint supports the
[Flare standard paging pattern <Icon icon="book" size={16} />](/concepts/paging).
<CrendentialSearchDescription/>

## Guides

See the guide for using this endpoint:
[Exporting a Domain's Credentials <Icon icon="book" size={16} />](/guides/credentials-export-domain).

## Body Parameters

<ParamField body="size" type="number">
Maximum size of the JSON object that will be returned (maximum 10 000)
</ParamField>

<ParamField body="from" type="string">
The `next` value from the last response.
</ParamField>

<ParamField body="order" type="string" default="desc">
The order in which the results will be returned. (`asc` or `desc`)
</ParamField>

<ParamField body="query" type="object">
One of the supported queries.
<Tabs>

<Tab title="Domain Query">
```json
{
"type": "domain",
"fqdn": "<string>"
}
```
</Tab>

<Tab title="Auth Domain Query" >
This query will match the domain of the service that this credential might have been used to log in to.
```json
{
"type": "auth_domain",
"fqdn": "<string>"
}
```
</Tab>

<Tab title="Password Query">
```json
{
"type": "secret",
"secret": "<string>"
}
```
</Tab>

<Tab title="Email Query">
```json
{
"type": "email",
"email": "<string>"
}
```
</Tab>

<Tab title="Keyword Query" >
This query will match with the credential's username, which is the portion of the `identity_name` that preceeds `@`.
```json
{
"type": "keyword",
"keyword": "<string>"
}
```
</Tab>

</Tabs>
</ParamField>

<ParamField body="filters" type="object">
<Expandable defaultOpen>
<ParamField body="imported_at" type="object">
<Note>
This filter only works for Auth Domain Queries. It will be ignored if used with other query types.
</Note>

<Expandable>
<ParamField
body="gte"
type="string"
placeholder="Example: 2024-01-01T00:00:00+00:00"
>
Matches values greater than or equal to the specified timestamp.

Format: ISO-8601
</ParamField>

<ParamField
body="lte"
type="string"
placeholder="Example: 2024-01-01T00:00:00+00:00"
>
Matches values lesser than or equal to the specified timestamp.

Format: ISO-8601
</ParamField>
</Expandable>
</ParamField>
</Expandable>
</ParamField>
<CrendentialSearchCommon />
12 changes: 12 additions & 0 deletions docs/api-reference/v4/endpoints/credentials-global-search.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,12 @@
---
title: "Search Credentials"
api: "POST https://api.flare.io/firework/v4/credentials/_search"
---

import CrendentialSearchCommon from '/snippets/endpoint-credential-search-common.mdx';
import GlobalSearchApiQuotaNote from '/snippets/global-search-api-quota-note.mdx';
import CrendentialSearchDescription from '/snippets/endpoint-credential-search-description.mdx';

<GlobalSearchApiQuotaNote />
<CrendentialSearchDescription />
<CrendentialSearchCommon />
2 changes: 1 addition & 1 deletion docs/api-reference/v4/endpoints/global-search.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
---
title: "Search"
title: "Search Events"
api: "POST https://api.flare.io/firework/v4/events/global/_search"
authMethod: "bearer"
---
Expand Down
13 changes: 7 additions & 6 deletions docs/docs.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -91,15 +91,16 @@
"api-reference/v4/endpoints/identifier-feed",
"api-reference/v4/endpoints/identifier-group-feed"
]
},
{
"group": "Global Search",
"pages": [
"api-reference/v4/endpoints/global-search"
]
}
]
},
{
"group": "Global Search API",
"pages": [
"api-reference/v4/endpoints/global-search",
"api-reference/v4/endpoints/credentials-global-search"
]
},
{
"group": "Account and Session Takeover Prevention (ASTP) API",
"pages": [
Expand Down
154 changes: 154 additions & 0 deletions docs/snippets/endpoint-credential-search-common.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,154 @@
<ResponseExample>

```json Response Example
{
"items": [
{
"domain": "scatterholt.com",
"hash": "B@dPassw0rd",
"hash_type": null,
"id": 33880703907,
"identity_name": "[email protected]",
"imported_at": "2024-07-22T19:25:52.893439+00:00",
"known_password_id": null,
"source": {
"breached_at": null,
"description_en": "Collection of multiple combo lists (emails and passwords) exchanged on illicit networks.",
"description_fr": "Collection de multiples listes \"combos\" (adresses courriel et mots de passe) \u00e9chang\u00e9es sur des r\u00e9seaux illicites.",
"id": "combolists",
"is_alert_enabled": true,
"leaked_at": null,
"name": "Combolists"
},
"source_id": "combolists"
},
{
"domain": "scatterholt.com",
"hash": "1qaz2wsx",
"hash_type": "unknown",
"id": 33880703906,
"identity_name": "[email protected]",
"imported_at": "2024-07-22T19:25:52.893439+00:00",
"known_password_id": null,
"source": {
"breached_at": null,
"description_en": "Collection of multiple combo lists (emails and passwords) exchanged on illicit networks.",
"description_fr": "Collection de multiples listes \"combos\" (adresses courriel et mots de passe) \u00e9chang\u00e9es sur des r\u00e9seaux illicites.",
"id": "combolists",
"is_alert_enabled": true,
"leaked_at": null,
"name": "Combolists"
},
"source_id": "combolists"
}
],
"next": "WyJjb20uc2NhdHRlcmhvbHQiLCAxNjczNjg4ODg4NV0"
}
```

</ResponseExample>

## Paging

This endpoint supports the
[Flare standard paging pattern <Icon icon="book" size={16} />](/concepts/paging).

## Body Parameters

<ParamField body="size" type="number">
Maximum size of the JSON object that will be returned (maximum 10 000)
</ParamField>

<ParamField body="from" type="string">
The `next` value from the last response.
</ParamField>

<ParamField body="order" type="string" default="desc">
The order in which the results will be returned. (`asc` or `desc`)
</ParamField>

<ParamField body="query" type="object">
One of the supported queries.
<Tabs>

<Tab title="Domain Query">
```json
{
"type": "domain",
"fqdn": "<string>"
}
```
</Tab>

<Tab title="Auth Domain Query" >
This query will match the domain of the service that this credential might have been used to log in to.
```json
{
"type": "auth_domain",
"fqdn": "<string>"
}
```
</Tab>

<Tab title="Password Query">
```json
{
"type": "secret",
"secret": "<string>"
}
```
</Tab>

<Tab title="Email Query">
```json
{
"type": "email",
"email": "<string>"
}
```
</Tab>

<Tab title="Keyword Query" >
This query will match with the credential's username, which is the portion of the `identity_name` that preceeds `@`.
```json
{
"type": "keyword",
"keyword": "<string>"
}
```
</Tab>

</Tabs>
</ParamField>

<ParamField body="filters" type="object">
<Expandable defaultOpen>
<ParamField body="imported_at" type="object">
<Note>
This filter only works for Auth Domain Queries. It will be ignored if used with other query types.
</Note>

<Expandable>
<ParamField
body="gte"
type="string"
placeholder="Example: 2024-01-01T00:00:00+00:00"
>
Matches values greater than or equal to the specified timestamp.

Format: ISO-8601
</ParamField>

<ParamField
body="lte"
type="string"
placeholder="Example: 2024-01-01T00:00:00+00:00"
>
Matches values lesser than or equal to the specified timestamp.

Format: ISO-8601
</ParamField>
</Expandable>
</ParamField>
</Expandable>
</ParamField>
1 change: 1 addition & 0 deletions docs/snippets/endpoint-credential-search-description.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
Returns a list of credentials matching the query provided.