Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.pecta.ai/llms.txt

Use this file to discover all available pages before exploring further.

Pecta’s security model is designed around one principle: the data that matters most to you — bid payloads, MCP tool inputs and outputs, user content — never leaves your infrastructure. Gates evaluate locally inside your process, and only the result metadata is batched and shipped to the cloud asynchronously. This section explains what Pecta stores, how API keys work, and how telemetry is authenticated.

​
What Pecta stores

Pecta persists only evaluation metadata. User payloads are never transmitted, queued, or written to disk.
StoredNot stored
agent_idBid request / response payloads
Gate nameMCP tool inputs and outputs
Pass / fail booleanUser message content
Reason string (gate-generated, not from payload)Any field from ctx.input or ctx.output
latency_ms
timestamp (ISO 8601 UTC)
The @pecta/core SDK enforces this boundary before any network call is made: it strips the EvaluationResult down to the metadata fields above and discards everything else, including any details objects that might reference user data.
Do not put sensitive content inside gate reason strings in custom gates. Reason strings are stored as-is in the Pecta cloud and appear in dashboard event feeds.

​
API key types

Pecta issues two key types with different trust levels:
PrefixTypeUse
pk_live_PublishableSafe for config files, CLI arguments, and client-side code. Use for telemetry ingest and evaluation requests.
sk_live_SecretServer-only. Required for admin operations and HMAC signing. Never commit to source control or include in config files visible to end users.
Keys are stored securely and never retrievable after creation. The plaintext is shown exactly once at creation time.
If a sk_live_ key is exposed, revoke it immediately from Settings → API keys in the dashboard. Revocation takes effect within seconds.

​
HMAC signing for telemetry

When you initialise PectaTelemetry with hmac: true, every batch POST to /v1/ingest includes an X-Pecta-Signature header: 
X-Pecta-Signature: sha256=<hex digest>
The digest is HMAC-SHA256(secretKey, requestBody). The Pecta API verifies the signature before accepting the batch, ensuring that telemetry cannot be spoofed or replayed by a third party who only has your publishable key. 
const telemetry = new PectaTelemetry({
  publishableKey: process.env.PECTA_PUBLISHABLE_KEY!,
  secretKey: process.env.PECTA_SECRET_KEY!,
  hmac: true,
});
HMAC signing requires a sk_live_ secret key. Keep it in an environment variable or a secrets manager — never hardcode it.

​
Gates run locally; only results reach the cloud

In SDK and proxy mode, gate evaluation is entirely local:
  1. Your agent produces output.
  2. engine.evaluate() runs gates inside your process (< 15 ms for RTB, < 50 ms for MCP).
  3. The EvaluationResult is returned to your code.
  4. telemetry.track(result) strips the result to metadata and adds it to an in-memory buffer.
  5. The buffer is flushed asynchronously to POST /v1/ingest in the background.
Steps 1–3 complete before any network activity begins. If the flush fails, Pecta retries once after 1 second and then drops the batch silently. Gate decisions are never delayed by network conditions.
In REST API mode (Mode 3), gate evaluation runs server-side on Pecta infrastructure. This is the only mode in which agent output travels over the network. If this is a concern, use the SDK or proxy mode instead.

​
Per-mode key requirements

ModeRequired keyHMAC
MCP proxy, local-onlyNone—
MCP proxy, cloud telemetrypk_live_Optional
In-process SDK, telemetrypk_live_Optional with sk_live_
In-process SDK, HMAC signingpk_live_ + sk_live_Required
REST API, evaluationpk_live_—
REST API, admin operationssk_live_—

​
Additional hardening

  • Every /v1/* endpoint is scoped to the authenticated organization — you can never read another organization’s data even with a valid key.
  • All endpoints are rate-limited. Exceeding the limit returns 429 RATE_LIMITED.
  • JSON-RPC messages larger than 1 MB are dropped by the proxy before gate evaluation (--max-message-size).
  • No secrets appear in proxy or SDK logs. The publishable key prefix (pk_live_) is safe to log; full key values are not.