Basics

Honeypot can be used in two ways: through our SDKs for client-side and server-side integration, or via direct REST API calls. Choose the approach that best fits your use case.

SDK Usage

Using the Honeypot SDK is the recommended approach for most applications. Simply load the library and track events.

Javascript

// Load your honeypot
honeypot.setup({ url: 'https://<your-honeypot-url>/js' })

// Optionally identify the user if you have an account ID, email, etc
honeypot.identify('you@example.com')

// Track an individual event
await honeypot.track('Login')

// Get the threat signals
honeypot.get().then((honey) => {
    console.log(honey.handprint_id)
})

Python (Vanilla)

from honeypot import honeypot

insights = honeypot(url)
    .set_ip(ip)
    .identify("user123")
    .track("Some event") # or track_async

Python (Django)

from honeypot import honeypot

honeypot(url)
    .event_paths(
        post={
            # Event name -> endpoint
            "Login": "/api/auth",
        },
    )
    .set_ip(ip)
    .with_request(request)
    .identify("user123")
    .track("Some event") # or track_async

The data that the SDK returns is documented here.

REST API Usage

For server-to-server communication or custom integrations, you can send events directly to your Honeypot via REST API.

Getting your write key

1. Navigate to your Honeypot in the UI
2. Go to Honeypot → Security
3. Copy your write key

Sending Events

bash

curl -X POST https://your-honeypot-url.com/events \
  -H "Authorization: Bearer <YOUR_WRITE_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "event": "user_action",
    "identity": "user@example.com",
    "properties": {
      "action": "clicked_button",
      "button_name": "submit"
    }
  }'

Request Parameters

Parameter	Type	Required	Description
event	string	Yes	The name of the event
identity	string	No	User identifier (email, user ID, etc.)
properties	object	No	Additional event properties

Keep your write key secure

Your write key provides access to send events to your Honeypot. Never expose it in client-side code or commit it to version control.

Response

The response will contain insights for the given event. See the Gathering honey section for more information about the response data.