PhishGuard API

1. Get your tenant provisioned by emailing sales@socshield.dz.
2. Sign in to your tenant dashboard and create an API key under /api. Plaintext keys are shown once at creation — copy them then.
3. POST your first email to the ingest endpoint:

curl -X POST https://api.phishguard.socshield.dz/api/v1/email/ingest \
  -H "X-API-Key: $PHISHGUARD_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message_id": "<abc123@mail.gmail.com>",
    "subject":    "Urgent: verify your account",
    "from":       "no-reply@suspicious.example",
    "to":         "alice@your-company.com",
    "raw":        "Received: from ...\nFrom: ...\nSubject: ...\n\nBody here"
  }'

You get back an email_id and a verdict status that starts as pending. The verdict moves to phishing, safe, or unsure after analysis. Subscribe to the verdict.set webhook to get notified the moment the verdict lands.

Every request must include your API key in the X-API-Key header. Keys are scoped to a tenant and tied to a list of allowed scopes (ingest, read, etc.) which you set at creation.

X-API-Key: pg_<16-char-prefix>_<48-char-secret>

• IP allowlist — optional, set per key. Requests from outside the allowlist return 403 ip_not_allowed.
• Expiry — optional, set per key. Expired keys return 401 expired_key.
• Tenant status — if your tenant is suspended or archived all keys return 403 regardless of validity.
• Rotation — rotate a key from the dashboard; the old one is revoked immediately and the new plaintext is shown once.

Every response carries an X-Request-Id header. Paste it in any support email and we'll find your request in our logs immediately.

PhishGuard enforces two limits independently: a per-key sliding-60-second rate limit (set per key, defaults to 60/min) and a per-tenant 30-day email-ingest quota (set per tenant by your account manager).

Every response includes these headers (omitted on keys with no rate limit):

X-RateLimit-Limit:     60
X-RateLimit-Remaining: 47
X-RateLimit-Reset:     1716800000  # unix seconds

When a limit is exceeded the API returns 429 with a JSON body that explains which limit you hit:

{
  "error": "Rate limit exceeded",
  "code":  "rate_limited",
  "limit": 60,
  "used":  60,
  "retryAfterSec": 60,
  "request_id": "req_..."
}

The /api/v1/email/ingest endpoint is the only one that counts toward your monthly quota. Read endpoints (e.g. /email/<id>) and notification polls don't.

Register a webhook from your dashboard at /api → Webhooks. We POST a signed JSON payload to your URL whenever a subscribed event fires. The only event currently fired is verdict.set.

Headers we send

X-PhishGuard-Signature: <hex HMAC-SHA256 of the raw body>
X-PhishGuard-Event:     verdict.set
X-PhishGuard-Delivery:  <unique-delivery-id>
User-Agent:             PhishGuard-Webhook/1.0

Sample payload

{
  "event":      "verdict.set",
  "timestamp":  "2026-05-27T10:14:00Z",
  "tenant_id":  "uuid",
  "webhook_id": "uuid",
  "data": {
    "email_id":  "uuid",
    "verdict":   "phishing",     // phishing | safe | unsure
    "reason":    "Brand impersonation + suspicious link",
    "set_by":    "analyst@socshield.dz",
    "set_at":    "2026-05-27T10:13:58Z"
  }
}

Verification (compute the HMAC over the RAW body, not the parsed JSON)

import { createHmac, timingSafeEqual } from 'crypto'

function verify(rawBody, signatureHeader, secret) {
  const expected = createHmac('sha256', secret).update(rawBody).digest('hex')
  // Constant-time compare to avoid timing attacks.
  const a = Buffer.from(signatureHeader, 'hex')
  const b = Buffer.from(expected, 'hex')
  return a.length === b.length && timingSafeEqual(a, b)
}

Every error response is JSON with the same shape:

{
  "error":      "Human-readable message",
  "code":       "machine_code",
  "request_id": "req_..."
}