Auth

The API implements authentication and authorization throughout most endpoints. In this section you may learn what this means and how to handle it in your automation/integrations.

Authentication

Authentication is the process of determining whether someone or something is who or what they say they are. As the client, this means you need to provide a piece of data (cookies, tokens, metadata, etc.) to the server. As the server, this means you need to check that the piece(s) of data is valid and correctly identifies the user at that point in time (and place, sometimes).

All IntelSentry API endpoints are authenticated, meaning the client must supply a valid API key with each request. In case you haven’t yet, you may generate an API key here (note that you must have a Researcher PRO or higher subscription tier to access this feature).

In order to supply the token, simply append the following header in the request.

Authorization: Bearer <token>

As such, an example request would look like the following.

GET https://api.intelsentry.io/v1/info/token
Authorization: Bearer <token>

You may quickly try it for yourself via cURL.

curl -v -X GET -H "Authorization: Bearer <token>" https://api.intelsentry.io/v1/info/token

curl.exe -v -X GET -H "Authorization: Bearer <token>" https://api.intelsentry.io/v1/info/token

Authorization

Authorization, on the other hand, corresponds to the process of validating that a previously authenticated user or entity has access to a certain resource at that point in time (and place, sometimes). As the client, this means you should not be able to access the resources of other users or higher tier data. As the server, this means you should not grant access to the clients if they are trying to access such resource.

In IntelSentry API, this effectively means you won’t (or shouldn’t) be able to access resources owned by other users, such as the search history or personal/login data. Moreover, this also means you won’t be able to access more data than your subscription tier permits.

The only current exception to this rule applies to the data that is searchable. Meaning all users will be able to search through exactly the same data, though of course different size limits apply based on the subscription.

In order to obtain your current limit through the API, you may use the following endpoint

GET https://api.intelsentry.io/v1/info/user
Authorization: Bearer <token>

HTTP/1.1 200
Content-Type: application/json
 
{
    "email": "test@example.com",
    "full_name": "Example User",
    "subscription": "Researcher PRO",
    "subscription_begins": 1742763329000,
    "subscription_ends": 1742849729000,
    "searches_left": 1500
}

If everything is correct, the response should contain the searches_left JSON key, which corresponds to the available search tokens for your user at that time.

When searching data, you will consume your tokens based on your max results limit, depending on the subscription tier. This means, for example, that 1 search token corresponds to 2000 leak results with the Researcher PRO subscription.

However, many queries will go over that amount in total results size. In such cases, you may decide whether to spend 1 token for 2000 results, or x tokens for 2000 * x results, with x ∈ [1, ⌈results_size/results_per_token⌉]. You will always be able to consult the total results size for a given query before the execution of the search.