Developer Quickstart — KeyPulse API

01

Step 1

Get your API key

POST /api/v1/partners/register

          curl
          
        

          curl -X POST https://keypulse-5pj5.polsia.app/api/v1/partners/register \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Exchange",
    "email": "ops@acme.com"
  }'
        

Response

            json
          

            {
  "success": true,
  "api_key": "pk_live_a3f9d2e8c1b4...",   // save this — shown once
  "partner_id": 42,
  "partner_name": "Acme Exchange",
  "rate_limit": 100,                    // requests per hour
  "warning": "Save this API key now. It cannot be retrieved again."
}
          

Save your API key immediately. It's returned once and never stored in plaintext. Use it as the X-API-Key header in all subsequent requests.

02

Step 2

Send your first event

POST /api/v1/events/ingest

          curl
          
        

          curl -X POST https://keypulse-5pj5.polsia.app/api/v1/events/ingest \
  -H "Content-Type: application/json" \
  -H "X-API-Key: pk_live_a3f9d2e8c1b4..." \
  -d '{
    "key_id": "key_mpc_eth_signer_01",
    "event_type": "key_rotated",
    "timestamp": "2026-05-19T11:30:00Z",
    "metadata": {
      "reason": "scheduled_90d_rotation",
      "rotated_by": "ops-bot-v2",
      "previous_key_id": "key_mpc_eth_signer_00",
      "vault": "aws-kms-prod"
    }
  }'
        

Response

            json
          

            {
  "success": true,
  "event_id": 8847,
  "partner_id": 42,
  "key_id": "key_mpc_eth_signer_01",
  "event_type": "key_rotated",
  "timestamp": "2026-05-19T11:30:00.000Z",
  "created_at": "2026-05-19T11:30:01.432Z"
}
          

Valid event types: key_created, key_rotated, key_accessed, key_deleted, signing_operation, policy_violation. The metadata field accepts any JSON object — store whatever your platform tracks.

03

Step 3

Query your event history

GET /api/v1/events

          curl
          
          curl https://keypulse-5pj5.polsia.app/api/v1/events \
  -H "X-API-Key: pk_live_a3f9d2e8c1b4..."

Response

            json
          

            {
  "success": true,
  "partner_id": 42,
  "count": 1,
  "events": [
    {
      "id": 8847,
      "key_id": "key_mpc_eth_signer_01",
      "event_type": "key_rotated",
      "timestamp": "2026-05-19T11:30:00.000Z",
      "metadata": {
        "reason": "scheduled_90d_rotation",
        "rotated_by": "ops-bot-v2",
        "vault": "aws-kms-prod"
      },
      "created_at": "2026-05-19T11:30:01.432Z"
    }
  ]
}
          

Filter by key: append ?key_id=key_mpc_eth_signer_01 to scope results to one key. Filter by event type with ?event_type=key_rotated. Returns up to 100 events, newest first.

04

Step 4

Set up real-time alerts

POST /api/v1/rules

Create an alert rule — tell KeyPulse which event type to watch and where to POST when it fires.

          curl — create rule
          
        

          curl -X POST https://keypulse-5pj5.polsia.app/api/v1/rules \
  -H "Content-Type: application/json" \
  -H "X-API-Key: pk_live_a3f9d2e8c1b4..." \
  -d '{
    "name": "Rotation alert",
    "event_type_match": "key_rotated",
    "webhook_url": "https://your-platform.com/webhooks/keypulse",
    "severity": "warning"
  }'
        

Response — 201 Created

            json
          

            {
  "success": true,
  "rule": {
    "id": 7,
    "partner_id": 42,
    "name": "Rotation alert",
    "event_type_match": "key_rotated",
    "webhook_url": "https://your-platform.com/webhooks/keypulse",
    "severity": "warning",
    "is_active": true,
    "created_at": "2026-05-22T04:00:00.000Z"
  }
}
          

Webhook payload format. When an ingested event matches your rule, KeyPulse POSTs to your webhook_url within milliseconds:

          json — webhook payload
          
        

          {
  "event_id": 8847,
  "event_type": "key_rotated",
  "key_id": "key_mpc_eth_signer_01",
  "timestamp": "2026-05-22T04:00:00.000Z",
  "metadata": { "reason": "scheduled_90d_rotation" },
  "rule_id": 7
}
        

Verify the signature. Every POST includes an X-KeyPulse-Signature header — HMAC-SHA256 of the raw body signed with your API key. Verify it before processing:

          node.js — signature check
          
        

          import crypto from 'crypto';

// In your Express webhook handler:
app.post('/webhooks/keypulse', (req, res) => {
  const sig      = req.headers['x-keypulse-signature'];
  const expected = crypto
    .createHmac('sha256', process.env.KEYPULSE_API_KEY)
    .update(JSON.stringify(req.body))
    .digest('hex');

  if (sig !== expected) return res.status(401).end();

  // Safe to process — signature verified
  const { event_type, key_id, rule_id } = req.body;
  res.status(200).json({ received: true }); // respond fast; process async
});
        

Auto-retry on failure. If your endpoint doesn't return 2xx, KeyPulse retries once automatically. Respond with 200 quickly — do heavy processing async.

You can also list and delete rules:

GET/api/v1/rules

DELETE/api/v1/rules/:id

            curl — list rules
            
            curl https://keypulse-5pj5.polsia.app/api/v1/rules \
  -H "X-API-Key: pk_live_a3f9d2e8c1b4..."

            curl — delete rule
            
            curl -X DELETE https://keypulse-5pj5.polsia.app/api/v1/rules/7 \
  -H "X-API-Key: pk_live_a3f9d2e8c1b4..."

From zero to live
in four requests.

Ready to go to production?

From zero to livein four requests.

Ready to go to production?

From zero to live
in four requests.