Authenticate your requests to the Pecta API

Every request to a /v1/* endpoint must carry a valid API key. Pecta issues two key types with different trust levels, and the @pecta/core SDK optionally signs telemetry payloads with an HMAC signature for additional integrity guarantees.

Key types

Pecta API keys follow the format pk_live_<32 chars> or sk_live_<32 chars>. The prefix tells you what the key is allowed to do.

Prefix	Type	Safe to expose?	Use for
`pk_live_`	Publishable	Yes — config files, `.env` on client	Reads, `/v1/evaluate`, telemetry ingest, MCP proxy
`sk_live_`	Secret	No — server environment only	Admin operations, HMAC signing

Keys are shown only once at creation time and stored as SHA-256 hashes in Pecta’s database.

Never embed a sk_live_ key in client-side code, browser bundles, or any repository that is or could become public. If a secret key is exposed, revoke it immediately from the dashboard.

Authorization header

Pass your key as a Bearer token on every /v1/* request:

Authorization: Bearer pk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Full example with curl:

curl https://api.pecta.ai/v1/agents \
  --header "Authorization: Bearer pk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

HMAC signing for telemetry

When the @pecta/core SDK is configured with a secretKey, it signs every ingest payload with HMAC-SHA256 and includes the signature in the X-Pecta-Signature request header. This lets Pecta verify the payload was not tampered with in transit. The header format is:

X-Pecta-Signature: sha256=<hex-digest>

The digest is computed as:

HMAC-SHA256(raw-request-body, sk_live_key)

Pecta computes the expected digest server-side and compares it using a constant-time comparison (timingSafeEqual) to prevent timing attacks. If the header is present but the digest does not match, the request is rejected:

{
  "error": "HMAC signature does not match",
  "code": "hmac_invalid",
  "status": 401
}

The X-Pecta-Signature header is optional. If you omit it, ingest proceeds without signature verification. Enable HMAC in the SDK with:

const telemetry = new PectaTelemetry({
  publishableKey: 'pk_live_...',
  secretKey: 'sk_live_...',
  hmac: true,
});

Enable HMAC signing whenever you use @pecta/core in an RTB or otherwise latency-critical environment where payload integrity matters.

401 response

When authentication fails, the API returns 401 with a machine-readable code field:

{
  "error": "missing or malformed Authorization header",
  "code": "auth_missing",
  "status": 401
}

Code	Cause
`auth_missing`	No `Authorization` header, or header is malformed
`auth_format`	Key does not match the `pk_live_` / `sk_live_` format
`auth_invalid`	Key not found in the database
`auth_revoked`	Key exists but has been revoked
`hmac_no_secret`	HMAC header was sent but no secret key is on file
`hmac_invalid`	HMAC digest does not match the request body

Overview

Endpoints

Authenticate your requests to the Pecta API

Key types

Authorization header

HMAC signing for telemetry

401 response

​Key types

​Authorization header

​HMAC signing for telemetry

​401 response

Key types

Authorization header

HMAC signing for telemetry

401 response