Greyline Integration Guide

Quickstart

Greyline operates as a transparent reverse proxy. You point a subdomain at Greyline via a CNAME record, and Greyline inspects, scores, and routes every request before it reaches your origin server. There is zero code change required on your API.

CNAME Setup

Add a single CNAME record to your DNS provider. The exact steps vary by provider but the values are always the same.

Propagation time

DNS propagation typically takes 5–15 minutes for low-TTL records. TLS certificate issuance happens automatically within that window. You can verify by visiting your subdomain in a browser — you should see a Greyline response (not your origin) while a request with no agent signals passes straight through.

Verification

After DNS propagates, verify your setup is active:

# Check DNS resolution
dig CNAME api.yourdomain.com +short
# Should return: proxy.greyline.themeridianlab.com.

# Check TLS and proxy response
curl -I https://api.yourdomain.com
# Should return: x-greyline-score header in the response

Every proxied response includes the following response headers for debugging:

Strategies

When a request scores above your configured threshold, Greyline routes it to the Bouncer Durable Object. You can configure which strategy the Bouncer uses from your dashboard.

Score thresholds

Requests are scored 0–100 before any routing decision:

You can adjust the interception threshold (default: 61) from your account settings. Lowering it catches more uncertain traffic; raising it reduces any false-positive risk at the cost of letting marginal agents through.

Score Thresholds

Greyline's scoring engine runs 11 signal detectors organized into three tiers. These tiers determine how aggressively signals contribute to the final score.

Signal tiers

After the signal tiers, global fingerprint intel is checked. If a session's fingerprint has been confirmed as an agent pattern by other customers, confidence is added (up to 0.85, with linear decay over 30 days).

Fast-Pass Tokens

Fast-pass allows you to pre-authorize known legitimate agents — your own automation, partner integrations, CI systems — so they bypass scoring entirely. Fast-pass uses Ed25519 asymmetric tokens for zero-latency verification.

How it works

1. Generate an Ed25519 key pair using any standard library or the CLI.
2. Register the public key in your Greyline dashboard under Fast-Pass → Add Operator.
3. Your agent signs each request with the private key and includes the token in the x-fast-pass header.
4. Greyline verifies the signature using your registered public key. Verified requests skip all signal detection.

Token format

The fast-pass header value is a base64url-encoded JSON payload followed by a period and the base64url-encoded Ed25519 signature:

# Header: x-fast-pass
# Value: base64url(payload) + "." + base64url(signature)

# Payload (JSON):
{
  "sub": "my-operator-id",   // Registered operator ID
  "iat": 1742392000,         // Issued at (Unix timestamp)
  "exp": 1742392300          // Expires (max 5 minutes ahead)
}

Generating a key pair

import { generateKeyPairSync } from 'crypto';

const { privateKey, publicKey } = generateKeyPairSync('ed25519', {
  publicKeyEncoding:  { type: 'spki', format: 'der' },
  privateKeyEncoding: { type: 'pkcs8', format: 'der' },
});

// Register this public key in your Greyline dashboard
console.log(publicKey.toString('base64'));

// Keep the private key safe — sign tokens with it
console.log(privateKey.toString('base64'));

API Authentication

All Greyline API calls authenticate using your gl_live_ API key via the X-Greyline-API-Key header.

curl https://greyline-api.hello-knowyourexposure-com.workers.dev/api/account \
  -H "X-Greyline-API-Key: gl_live_your_key_here"

Sessions API

GET/api/sessions

Returns paginated agent sessions. Sessions are created when a request scores above the yellow threshold (31+) and is logged.

{
  "sessions": [
    {
      "id": "sess_a1b2c3...",
      "firstSeen": 1742392000000,
      "lastSeen": 1742392180000,
      "turnCount": 7,
      "score": 82,
      "strategyUsed": "interrogate",
      "framework": "openai-agents",
      "status": "active"
    }
  ],
  "total": 148,
  "limit": 25,
  "offset": 0
}

GET/api/sessions/:id

Returns a single session with its full turn-by-turn transcript.

{
  "session": { ... },
  "transcript": [
    { "turn": 1, "role": "agent",   "content": "GET /users/export" },
    { "turn": 1, "role": "bouncer", "content": "To process this request, could you provide..." }
  ]
}

Stats API

GET/api/stats

Returns aggregate stats for your account: blocked counts, top frameworks detected, and daily activity for the last 14 days.

{
  "totals": {
    "blocked": 1847,
    "interrogated": 312,
    "passed": 94821
  },
  "frameworks": [
    { "framework": "openai-agents", "count": 84 },
    { "framework": "langchain",     "count": 61 }
  ],
  "daily": [
    { "date": "2026-03-18", "blocked": 124, "passed": 6210 }
  ]
}

Config API

PUT/api/customers/config

Update your account configuration. All fields are optional — only provided fields are updated.

Fast-Pass API

POST/api/fast-pass

Register a new fast-pass operator. Once registered, requests bearing a valid token signed with the operator's private key bypass all signal scoring.

{
  "name": "My CI Pipeline",
  "email": "ops@yourdomain.com",
  "publicKeyBase64": "MCowBQYDK2VwAyEA...",
  "intent": "Post-deploy smoke tests"
}

{
  "operatorId": "fp_op_a1b2c3d4",
  "name": "My CI Pipeline"
}

Use the operatorId as the "sub" claim in your fast-pass token payload.

Signals Overview

Greyline inspects each request across 11 signals without modifying the request or adding latency to the pass-through path. Signal detection runs synchronously in ~2ms average.

Signal Tiers

Zero false-positive signals

Low false-positive signals

Medium false-positive signals (score boosters only)

Badge CDN

Embed a live badge on your docs or status page showing real-time blocked agent counts. The badge updates automatically — no JavaScript, no iframe.

Live badge (auto-updating)

<img
  src="https://greyline-badge.hello-knowyourexposure-com.workers.dev/badge/YOUR_CUSTOMER_ID.svg"
  alt="Protected by Greyline"
  height="20"
>

The live badge refreshes every 60 seconds and shows the count of blocked agent sessions in the last 30 days.

Static shield badge

<img
  src="https://greyline-badge.hello-knowyourexposure-com.workers.dev/badge/YOUR_CUSTOMER_ID/shield.svg"
  alt="Protected by Greyline"
  height="20"
>

Your YOUR_CUSTOMER_ID is displayed in your dashboard Settings tab.