Getting Started

Review the steps to integrate User Intel into your app

Introduction

The User Intel service must be enabled from the Pangea Console before use. Make sure you have access to the Pangea Console and you’ve created a project.

note

To create a project or learn about projects, visit Creating a project.

Create a token

Expand for details

Create a token so that you can access the User Intel endpoints:

1. Go to the Pangea Console and click User Intel in the left-hand navigation menu. The User Intel Overview page will appear.
2. On the User Intel Overview page, you'll see a notification asking you to set a service token. Click Create new token toward the bottom right side of your screen.
3. You’ll be prompted to create a token. Enter a Token name and select an Expiration Date. You may also create a token for all Intel services if you wish.
4. Once configured, the token is available in the Tokens section of the File Intel Overview page.

Select a provider as default

Expand for details

Providers can be selected as default in the Pangea Console . Setting a provider as default in the Pangea Console means your API request calls will use this provider, unless another provider is specified as part of your API request.

To select a provider as default for an API:

1. Go to the Pangea Console
2. On the left-hand navigation menu, select User Intel
3. Go to Settings
4. Switch on Default for your preferred provider

tip

You can override the default provider by specifying their name in the provider field when making an API request to the user/breached endpoint. This is helpful if your default provider returns a verdict of Unknown and you want a second opinion from another provider.

Test the service

The interactive User Intel API Reference allows you to test API endpoints from the documentation. This is an easy way to play around with users and providers to see what kind of data is returned.

Configure your app for communication with the Pangea service

For your app to communicate with the Pangea service, you must put the values of the following Configuration Details into the PANGEA_INTEL_TOKEN and PANGEA_DOMAIN environment variables:

• token
• domain

These Configuration Details are created when you enable User Intel and can be found in the Overview section under User Intel.

Set environment variables

To set each variable in bash:

export PANGEA_DOMAIN="yourServiceDomain"

export PANGEA_INTEL_TOKEN="yourAccessToken"

Make an API call

Make an API call to the user/breached endpoint to see if a user's or an array of up to 100 users' data has been compromised.

API calls containing a single user will return a 200 code and the results. When making an API call that includes multiple users, the response will be asynchronous and return a 202 instead of immediately returning the results. You will then need to poll for the results. For more information, visit our Asynchronous API response page.

All you need to construct an API call is an email, phone_number, ip, or username. All other parameters are optional. Your API request might look like the example below:

POST/v2/user/breached

cURL

Code Snippet Language

curl -sSLX POST 'https://user-intel.'"$PANGEA_DOMAIN"'/v2/user/breached' \
-H 'Authorization: Bearer '"$PANGEA_INTEL_TOKEN" \
-H 'Content-Type: application/json' \
-d '{"provider":"spycloud","emails":["test@example.com","test2@example.com"]}'

Receive a response

The User Intel service will send a JSON response, like the one below:

{
  "result": {
    "data": {
      "found_in_breach": true,
      "breach_count": 3
    },
    "parameters": {...},
    "raw_data": {
      "cursor": "",
      "hits": 1,
      "results": [
        {
          "account_last_activity_time": "2018-11-28T00:54:33Z",
          "account_login_time": "2018-11-28T17:24:19Z",
          "account_modification_time": "2018-11-28T18:30:36Z",
          "account_signup_time": "2018-11-05T00:47:45Z",
          "document_id": "0f3996bb-4070-4c63-a93b-8e2a2c740b47",
          "domain": "snet.net",
          "emails": "delete.linda.salamacha@snet.net",
          "email_domain": "snet.net",
          "email_username": "delete.linda.salamacha",
          "ip_addresses": [
            "74.89.49.67"
          ],
          "password": "$2a$10$Q7ywnq6CKkyau0FteXRCcOihBo3yLf6s0.Iwu8Si13BUgkEwe8XpW",
          "password_type": "bcrypt",
          "phone": "8005550123",
          "record_modification_date": "2021-03-26T00:00:00Z",
          "severity": 5,
          "source_id": 17650,
          "spycloud_publish_date": "2020-05-14T00:00:00Z"
        }
      ]
    }
  },
  "request_id": "prq_x6fdiizbon6j3bsdvnpmwxsz2aan7fqd",
  "request_time": "2022-09-21T17:24:33.105Z",
  "response_time": "2022-09-21T17:24:34.007Z",
  "status": "success"
}

The JSON response above indicates that the user’s email has been compromised.

Understand and review results​

The API response sent by User Intel includes various fields and values; however, the ones listed below give you the most information about the disposition of a user’s data. To learn about more response fields, visit the User Intel API Reference

data	The objects nested under data will clearly indicate if a user’s data has been involved in a breach and how many times the user’s data has been involved in said breaches. found_in_breach - A flag indicating if there was any match to the hash prefix. Prefix only applies to passwords. This parameter can return whatever criteria you were looking up. breach_count - Total number of instances of the prefix found in breach data. Prefix may be found multiple times in a single breach incident.
summary	A summary of the various categories associated with a user’s data, which help illustrate why a user received a particular verdict.
raw_data	Raw data returned by the provider you specified in the API request. You can investigate the raw data if it’s meaningful to your use case or if you want to supply it to your users. You must set the raw field to true to receive this data.

Share your implementation

Reach out to the Pangea community on our

Discourse to let us know how you've integrated User Intel into your application.

Was this article helpful?

Contact us