Postman Guide - Accessing DarkSight Intel APIs

Yes! All DarkSight Intel APIs can be accessed directly via Postman. This guide shows you how.

Quick Answer

✅ Yes, all APIs are accessible via Postman

You have two options:

Use the Postman Collection (Recommended) - Automated token management
Manual Setup - Copy token from browser

Method 1: Using Postman Collection (Recommended)

The easiest way to use the APIs in Postman is with the pre-configured collection.

Step 1: Import Collection

Open Postman
Click "Import" button (top left)
Click "Upload Files" or drag and drop
Select: docs/postman-collection-enterprise.json
Click "Import"

Step 2: Configure Variables

Click on collection "DarkSight Intel Enterprise API"
Go to "Variables" tab
Set the client_secret variable:
- Get it from: Auth0 Dashboard → Applications → darksight-intel-api → Settings → Client Secret
- Click "Show" to reveal (or rotate if needed)
- Paste into client_secret variable

Pre-configured variables (already set):

✅ base_url: https://platform-dev.omegablack.io/api/v1
✅ auth0_domain: omegablackdev.us.auth0.com
✅ api_audience: https://api.omegablackdev.com
✅ client_id: JCTZ7KprKtG3v0cbDKNCoeEAM2FpvXHs
⚠️ client_secret: YOU NEED TO SET THIS
✅ access_token: Auto-populated after Get Access Token

Step 3: Get Access Token

Expand "Authentication" folder
Click "Get Access Token" request
Click "Send"
Token is automatically saved to access_token variable ✅

Step 4: Use Any Endpoint

All requests now automatically use the token! Try:

Dashboard → Get Dashboard Metrics
Fraud Intelligence → Get Fraud Overview
CVE Intelligence → Get Trending CVEs
Search → Unified Search
Reports → Get Reports
Brand Intelligence → Analyze Domain

Method 2: Manual Setup (Browser Token)

If you prefer to use a token from your browser session:

Step 1: Get Token from Browser

Log into platform-dev:
- Go to: https://platform-dev.omegablack.io
- Log in with your credentials
Open Browser DevTools:
- Press F12 (Windows/Linux) or Cmd+Option+I (Mac)
- Or right-click → "Inspect"
Go to Network Tab:
- Click the "Network" tab in DevTools
- Make sure it's recording (red circle should be active)
Trigger an API Request:
- Navigate to any page that makes API calls (like Brand Intelligence page)
- Or click on any feature that loads data
- You should see API requests appear in the Network tab
Find an API Request:
- Look for requests to /api/v1/ endpoints
- Click on one (e.g., /api/v1/dashboard/metrics)
Copy the Authorization Header:
- In the request details, click "Headers" tab
- Scroll down to "Request Headers"
- Find Authorization: Bearer ...
- Copy the entire token (everything after "Bearer ")

Step 2: Configure Postman

Create a new request in Postman
Set the URL: https://platform-dev.omegablack.io/api/v1/dashboard/metrics
Go to Authorization tab:
- Type: Select "Bearer Token"
- Token: Paste your token
Click Send

Step 3: Use Environment Variables (Optional)

To avoid pasting the token in every request:

Create Environment:
- Click "Environments" in left sidebar
- Click "+" to create new environment
- Name it "DarkSight Intel"
Add Variable:
- Variable name: access_token
- Initial value: Paste your token
- Current value: Paste your token
- Click "Save"
Use in Requests:
- Select your environment from dropdown (top right)
- In Authorization tab, use: Bearer {{access_token}}

Available Postman Collections

1. Enterprise API Collection

File: docs/postman-collection-enterprise.json

Includes:

✅ Authentication (auto token management)
✅ Dashboard (metrics & trends)
✅ Fraud Intelligence (overview, cards, accounts)
✅ CVE Intelligence (vulnerabilities & trending)
✅ Vendors (list & details)
✅ Search (unified search)
✅ Reports (CRUD operations)
✅ Brand Intelligence (domain analysis)
✅ Cyber Attacks (attack data)
✅ Credentials (credential intelligence)
✅ Signals (threat signals)

2. Full API Collection

File: docs/postman-collection-full.json

Complete collection with all endpoints including external integrations.

3. ParseIntel External API

File: parseintel-api.postman_collection (3).json

External ParseIntel API collection (for reference).

Example Requests

Get Dashboard Metrics

GET https://platform-dev.omegablack.io/api/v1/dashboard/metrics?timeRange=7d
Headers:
  Authorization: Bearer {{access_token}}

Get Reports

GET https://platform-dev.omegablack.io/api/v1/reports?limit=50&offset=0
Headers:
  Authorization: Bearer {{access_token}}

Analyze Domain

POST https://platform-dev.omegablack.io/api/v1/brand-intelligence
Headers:
  Authorization: Bearer {{access_token}}
  Content-Type: application/json
Body (raw JSON):
{
  "domain": "example.com"
}

Unified Search

GET https://platform-dev.omegablack.io/api/v1/search?q=example&types=reports,signals&limit=10
Headers:
  Authorization: Bearer {{access_token}}

Create a Report

POST https://platform-dev.omegablack.io/api/v1/reports
Headers:
  Authorization: Bearer {{access_token}}
  Content-Type: application/json
Body (raw JSON):
{
  "reportTypeId": "threat-intelligence",
  "title": "New Report",
  "content": "Report content...",
  "status": "discovered"
}

Token Management

M2M Tokens (Postman Collection Method)

Expiration: 24 hours
Refresh: Run "Get Access Token" request again
Automatic: Token is saved automatically to collection variable

Browser Tokens (Manual Method)

Expiration: Varies (typically 24 hours)
Refresh: Log out and log back in, or refresh the page
Manual: Copy new token from browser DevTools

Troubleshooting

"401 Unauthorized" Error

For Postman Collection:

Make sure you ran "Get Access Token" first
Check client_secret variable is set correctly
Token expires after 24 hours - run "Get Access Token" again

For Manual Setup:

Token might be expired - get a new one from browser
Make sure you copied the entire token (no spaces or line breaks)
Verify you're logged into platform-dev

"403 Forbidden" Error

Your token doesn't have the required permissions
Check your user roles in Auth0
For admin endpoints, ensure you have admin role
For restricted endpoints, ensure you have required permissions (e.g., read:organizations)

"429 Too Many Requests" Error

You've exceeded the rate limit
Wait for the rate limit window to reset (15 minutes)
Check rate limit headers in response:
- X-RateLimit-Limit: Maximum requests allowed
- X-RateLimit-Remaining: Requests remaining
- X-RateLimit-Reset: When limit resets

Token Not Saving Automatically

Check Postman Console (View → Show Postman Console)
Verify the "Get Access Token" request returned 200 status
Manually set access_token variable if needed

Collection Variables Not Working

Make sure you're using {{variable_name}} syntax
Check variable name spelling (case-sensitive)
Verify variable is set in collection (not just environment)

Postman Tips

1. Use Pre-request Scripts

You can add pre-request scripts to automatically refresh tokens:

// Check if token is expired (example)
const token = pm.collectionVariables.get('access_token');
if (!token) {
    // Auto-refresh token
    pm.sendRequest({
        url: 'https://omegablackdev.us.auth0.com/oauth/token',
        method: 'POST',
        header: { 'Content-Type': 'application/json' },
        body: {
            mode: 'raw',
            raw: JSON.stringify({
                client_id: pm.collectionVariables.get('client_id'),
                client_secret: pm.collectionVariables.get('client_secret'),
                audience: pm.collectionVariables.get('api_audience'),
                grant_type: 'client_credentials'
            })
        }
    }, function (err, res) {
        if (res.json().access_token) {
            pm.collectionVariables.set('access_token', res.json().access_token);
        }
    });
}

2. Use Tests to Validate Responses

Add tests to verify API responses:

pm.test("Status code is 200", function () {
    pm.response.to.have.status(200);
});

pm.test("Response has data", function () {
    var jsonData = pm.response.json();
    pm.expect(jsonData).to.have.property('data');
});

3. Organize with Folders

The collection is already organized by feature:

Authentication
Dashboard
Reports
Signals
Credentials
Cyber Attacks
Brand Intelligence
Fraud Intelligence
CVE Intelligence
Vendors
Search
Organizations
User

4. Use Environments for Different Environments

Create separate environments for:

Development: https://platform-dev.omegablack.io/api/v1
Production: https://platform.omegablack.io/api/v1 (when available)

Security Best Practices

Never commit tokens to version control
Use environment variables instead of hardcoding tokens
Rotate client secrets regularly
Use M2M applications for automated access (not user tokens)
Set token expiration reminders
Don't share tokens - each user should get their own

Quick Start Checklist

Import Postman collection (docs/postman-collection-enterprise.json)
Set client_secret variable
Run "Get Access Token" request
Test with "Get Dashboard Metrics"
Explore other endpoints

Support

For issues:

Check API_REFERENCE.md for endpoint details
Review POSTMAN_SETUP.md for setup instructions
Contact your administrator for access issues

Next Steps

✅ Import collection
✅ Get access token
✅ Test endpoints
📚 Read API_REFERENCE.md for detailed documentation
🚀 Start building integrations!