REST API

Authentication

Authentication is simple - just use your Honeypot's write key as a Bearer token.

Getting your write key

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

Using the write key

Include the write key in the Authorization header of your requests:

curl

curl -X POST https://your-honeypot-url.com/events \
  -H "Authorization: Bearer eyJhbG..." \
  -H "Content-Type: application/json" \
  -d '{
    "event": "user_action",
    "identity": "user@example.com",
    "properties": {
      "action": "Test API event"
    }
  }'

python

import requests

# Replace with your write key
WRITE_KEY = "eyJhbG..."

# Replace with your honeypot URL
HONEYPOT_URL = "https://your-honeypot-url.com"

headers = {
    "Authorization": f"Bearer {WRITE_KEY}",
    "Content-Type": "application/json"
}

javascript

const WRITE_KEY = 'eyJhbG...';
const HONEYPOT_URL = 'https://your-honeypot-url.com';

const headers = {
  Authorization: `Bearer ${WRITE_KEY}`,
  'Content-Type': 'application/json',
};

kotlin

// For Android, use OkHttp or Retrofit
val WRITE_KEY = "eyJhbG..."
val HONEYPOT_URL = "https://your-honeypot-url.com"

val client = OkHttpClient()
val request = Request.Builder()
    .url("$HONEYPOT_URL/events")
    .addHeader("Authorization", "Bearer $WRITE_KEY")
    .addHeader("Content-Type", "application/json")
    .build()

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.

Sending Events

You can send events to your Honeypot using the /events endpoint.

Basic Example

curl

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

python

import requests

payload = {
    "event": "user_action",
    "identity": "user@example.com",
    "properties": {
        "action": "clicked_button",
        "button_name": "submit"
    }
}

response = requests.post(
    f"{HONEYPOT_URL}/events",
    headers=headers,
    json=payload
)
print(response.json())

javascript

const payload = {
  event: 'user_action',
  identity: 'user@example.com',
  properties: {
    action: 'clicked_button',
    button_name: 'submit',
  },
};

const response = await fetch(`${HONEYPOT_URL}/events`, {
  method: 'POST',
  headers: headers,
  body: JSON.stringify(payload),
});

const data = await response.json();
console.log(data);

kotlin

import okhttp3.*
import okhttp3.MediaType.Companion.toMediaType
import okhttp3.RequestBody.Companion.toRequestBody
import org.json.JSONObject

val payload = JSONObject().apply {
    put("event", "user_action")
    put("identity", "user@example.com")
    put("properties", JSONObject().apply {
        put("action", "clicked_button")
        put("button_name", "submit")
    })
}

val mediaType = "application/json; charset=utf-8".toMediaType()
val body = payload.toString().toRequestBody(mediaType)

val request = Request.Builder()
    .url("$HONEYPOT_URL/events")
    .addHeader("Authorization", "Bearer $WRITE_KEY")
    .post(body)
    .build()

client.newCall(request).enqueue(object : Callback {
    override fun onResponse(call: Call, response: Response) {
        val responseData = JSONObject(response.body?.string() ?: "{}")
        Log.d("Honeypot", "Response: $responseData")
    }

    override fun onFailure(call: Call, e: IOException) {
        Log.e("Honeypot", "Request failed", e)
    }
})

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

Response

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

Magic Properties

You can include magic properties in the properties parameter for additional intel, such as IP address, user agent, and more.

Mobile Integration

For mobile apps, you'll typically send events from your backend after receiving requests from the mobile client. This keeps your API key secure.

Recommended Architecture

┌──────────────┐      ┌──────────────┐      ┌──────────────┐
│  Mobile App  │ ──▶  │ Your Backend │ ──▶  │   Honeypot   │
│              │      │              │      │     API      │
└──────────────┘      └──────────────┘      └──────────────┘

1. Mobile app collects device info and sends to your backend
2. Your backend enriches with the device_id and sends to Honeypot
3. Honeypot returns risk signals
4. Your backend decides whether to allow the action

Device Registration Example

Track when a device is registered to a user:

curl

curl -X POST https://your-honeypot-url.com/events \
  -H "Authorization: Bearer $WRITE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "event": "Device Registration",
    "identity": "user-12345",
    "properties": {
      "device_id": "834d2f18-853b-4e60-92b3-4e1226306d70",
      "device_model": "Samsung Galaxy S24",
      "os_version": "Android 14",
      "registration_type": "new_device",
      "user_role": "bank_agent"
    }
  }'

kotlin

// From your Android app, send to YOUR backend first
val registrationPayload = JSONObject().apply {
    put("device_id", getDeviceId())
    put("device_model", Build.MODEL)
    put("os_version", "Android ${Build.VERSION.RELEASE}")
    put("user_id", currentUserId)
    put("user_role", "bank_agent")
}

// Your backend then forwards to Honeypot
yourBackendApi.registerDevice(registrationPayload) { result ->
    // Handle response
}

Transaction Verification Example

Verify device trust before processing a transaction:

curl

curl -X POST https://your-honeypot-url.com/events \
  -H "Authorization: Bearer $WRITE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "event": "Transaction",
    "identity": "user-12345",
    "properties": {
      "device_id": "834d2f18-853b-4e60-92b3-4e1226306d70",
      "transaction_type": "p2p_transfer",
      "amount": 50000,
      "currency": "NGN",
      "recipient_id": "user-67890"
    }
  }'

python

# In your backend, verify the transaction
response = requests.post(
    f"{HONEYPOT_URL}/events",
    headers=headers,
    json={
        "event": "Transaction",
        "identity": user_id,
        "properties": {
            "device_id": device_id,
            "transaction_type": "p2p_transfer",
            "amount": amount,
            "currency": "NGN",
            "recipient_id": recipient_id
        }
    }
)

result = response.json()

# Check risk signals
risk_score = result.get("risk_score", 0)
tags = result.get("current_tags", [])

if "vpn" in tags or "emulator" in tags:
    raise TransactionBlockedError("Suspicious device detected")

if risk_score > 0.7:
    require_additional_verification()

Response Fields for Mobile

Key response fields relevant to mobile device verification:

Field	Type	Description
device_id	string	The device identifier you passed in
handprint_id	string	Honeypot's cross-session device fingerprint
current_tags	array	Risk tags (e.g., vpn, emulator, rooted)
risk_score	number	Aggregated risk score (0.0 - 1.0)
device_id_details.age.days	number	How old the device ID is
behaviors	object	Behavioral analytics (transaction counts, etc.)

See the Event Payload Reference for the complete list of response fields.

Android SDK

For a streamlined mobile integration, use our Android SDK which handles device identification, offline queuing, and provides a native Kotlin/Java interface.