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 |
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.
/v1/* request:
Authorization: Bearer pk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
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>
HMAC-SHA256(raw-request-body, sk_live_key)
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
}
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 |
