DOCSEARCHbyAlgolia
Submit Docs

SentryPeer API Documentation

website·Indexed 32 days ago

https://docs.sentrypeer.com

API documentation for SentryPeer, a service for querying phone numbers and IP addresses collected from honeypots. Includes guides on authentication via OAuth2, webhook integration, and submitting honeypot events to track fraudster reconnaissance attempts.

Tokens
2K
Snippets
12
Records
19
Agent score
51%

What's inside SentryPeer

  1. Create a SentryPeer webhook

    SentryPeer webhooks notify your application via a POST request whenever a RESTful API query for Phone Numbers or IP Addresses resources finds a match (returns a 200 OK). To set up a webhook, navigate to the Integrations section of the SentryPeer dashboard and provide a name, a payload subject, a message, and the destination URL of your application.

  3. Authenticate API requests using a Bearer token

    After obtaining an OAuth2 access token, include it in the Authorization header of your API requests using the Bearer scheme to access protected resources.
    curl https://sentrypeer.com/api/phone-numbers/{phone-number} \
  --header "Authorization: Bearer {your_token_from_previous_step}"

  4. Obtain SentryPeer API client credentials

    To make requests to the SentryPeer API, you must first create an API client in the SentryPeer dashboard. Navigate to the Settings page to generate a Client ID and Client Secret, which are required to obtain an access token for authentication.

  5. Obtain an OAuth2 bearer token for SentryPeer API

    SentryPeer uses OAuth2 for API authentication. To obtain an access token, you must use your client credentials (found in the SentryPeer Settings section after creating a client). Tokens are valid for 24 hours. Send a POST request to the authorization server with your client_id, client_secret, the required audience, and the client_credentials grant type.
    curl --request POST --url https://authz.sentrypeer.com/oauth/token \
  --header 'content-type: application/json' \
  --data '{
            "client_id": "your_client_id",
            "client_secret": "your_client_secret",
            "audience": "https://sentrypeer.com/api",
            "grant_type": "client_credentials"
          }'

  6. Handle SentryPeer API error responses

    When a request is unsuccessful, the API returns a JSON response containing an error type and a descriptive message. Common error fields include error, reason, error_description, and message to help diagnose the issue.
    // Example: Invalid token
{
  "error": "Invalid token",
  "reason": "exp"
}

// Example: Permission denied
{
    "error": "insufficient_permissions",
    "error_description": "Insufficient claim for the token",
    "message": "Permission denied. Are you using the correct client_id to generate your token?"
}

  7. Submit Honeypot Events to SentryPeer

    Developers can use the Events model in the SentryPeer API to programmatically create and submit honeypot events that have been detected on their own networks.

  8. Manage API rate limits and 429 errors

    The SentryPeer API implements rate limiting to prevent abuse. If the limit is exceeded, the API returns a 429 Too Many Requests status code. Users can increase their limits by upgrading their plan.

    SentryPeer follows the RateLimit header fields for HTTP RFC draft specification. You can monitor your remaining quota via the response headers.

    # Example Rate Limit Headers
ratelimit-limit: 5
ratelimit-policy: 5;w=3600;policy="leaky bucket"
ratelimit-remaining: 3
ratelimit-reset: 3575

# Example 429 JSON Response
{
  "status": "429 Too Many Requests"
}

  9. Query IP Addresses via SentryPeer API

    The SentryPeer API provides an IP address model used to query the source addresses of early reconnaissance attacks collected from honeypots.

  10. Handle SentryPeer phone number query responses

    When querying a phone number via the API, if the number has not been detected by the honeypots, the API returns a JSON response indicating the number was not found.
    {
  "message": "Phone Number not found."
}

  11. SentryPeer Honeypot Event Model

    The honeypot event model is a JSON object representing a SIP probe. The following properties are required when sending events to the API:
    {
  "app_name": "string - Name of the application sending the event",
  "app_version": "string - Version of the application",
  "event_timestamp": "string - Timestamp of the event",
  "event_uuid": "string - Unique identifier (must be a valid UUID)",
  "created_by_node_id": "string - UUID of the node that created the event",
  "collected_method": "string - Method used to collect the event (responsive or passive)",
  "transport_type": "string - Transport type (UDP, TCP, or TLS)",
  "source_ip": "string - IP address of the attacker",
  "destination_ip": "string - IP address of the honeypot",
  "called_number": "string - The phone number the attacker is trying to call",
  "sip_method": "string - SIP method (e.g., INVITE, REGISTER, OPTIONS)",
  "sip_user_agent": "string - SIP User Agent (e.g., Avaya, Asterisk)",
  "sip_message": "string - The full SIP message content"
}

  12. Query an IP address for fraud reconnaissance

    Use the /api/ip-addresses/:ip-address endpoint to check if a specific source IP address has been registered by SentryPeer honeypots. This is useful for identifying and blocking IP addresses that are performing early reconnaissance attempts. If alert integrations are configured, you will receive notifications (Email, Slack, or Webhook) when a queried IP matches a known fraudster IP.
    curl https://sentrypeer.com/api/ip-addresses/X.X.X.X \
-H "Authorization: Bearer {token}"