> ## 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.

# Authenticate your requests to the Pecta API

> Learn how to use publishable and secret API keys, set the Authorization header, and sign telemetry batches with HMAC-SHA256 for 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.

<Warning>
  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.
</Warning>

## Authorization header

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

```bash theme={null}
Authorization: Bearer pk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
```

Full example with curl:

```bash theme={null}
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:

```json theme={null}
{
  "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:

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

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

## 401 response

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

```json theme={null}
{
  "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           |