Authentication
Authenticate requests to the Palveron API.
Every request to the Palveron API is authenticated with a bearer token — always the project API key.
curl -H "Authorization: Bearer pv_live_..." https://gateway.palveron.com/api/v1/verifyKey types
| Prefix | Used by | Lifecycle |
|---|---|---|
pv_live_ | Server-side SDKs, your own backend, and the Browser Guard extension | Issued per project, rotatable in Settings → API Keys |
Agent keys (ag_)
Registering an agent also mints an ag_ agent key. It is returned exactly once in the registration response, stored hashed at rest, and invalidated when the agent is revoked or rejected. This key is not accepted for API authentication today — it is reserved for future agent-scoped authentication. Every caller, including one acting for a single agent, authenticates with the project key.
Agents are attributed by their agent id instead — a plain CUID with no prefix (e.g. ckagent...): metadata.agent_id on verify requests, the X-Agent-Id header on the MCP proxy, or the X-Palveron-Agent header on the gateway LLM proxy.
Never commit keys to source control. The dashboard shows each key exactly once on creation. Store them in your secrets manager (AWS Secrets Manager, GCP Secret Manager, Vault) or in your CI/CD pipeline's secret store.
Key mode
Every project API key is a live key (prefix pv_live_); there is no separate test or sandbox key. A key's prefix does not change how a request is billed or anchored — that behaviour is a property of the project, not of the key.
For gas-free experimentation, use the dashboard Playground: it always runs against the Coston2 testnet and never anchors to the Flare mainnet, regardless of the project's configured network.
Error responses
Authentication and authorization errors return a plain, human-readable JSON body:
{ "error": "Unauthorized: Invalid API Key" }| Status | Meaning |
|---|---|
401 | Missing/invalid Authorization header, or the key is unknown/revoked |
403 | The key is valid but the caller can't perform this action, or the endpoint requires a higher tier (entitlement gates return e.g. {"error": "feature_not_entitled"}) |
429 | Rate limit hit — see below |
There is no machine-readable error-code or request-id field; branch on the HTTP status and, where documented per endpoint, on the error string.
Rate limits
Two independent limits, both resolved from your plan configuration (null = unlimited, 0 = locked, N = limit):
- Monthly quota — governance requests per month.
- Requests-per-minute (RPM) — only enforced when your plan sets one.
A 429 carries a structured body and standard headers:
{
"error": "Rate limit exceeded",
"tier": "pro",
"limit": 50000,
"limit_type": "monthly",
"remaining": 0,
"retry_after_secs": 86400,
"action": "top_up",
"detail": "Rate limit exceeded. Purchase additional governance traces to continue.",
"top_up_available": true
}Headers: Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, X-Rate-Limit-Type (rpm / monthly), X-RateLimit-Behavior, X-TopUp-Available.
The official SDKs retry transient 429s with exponential backoff and jitter; build the same behavior into custom clients.