Skip to main content
Pylva has three key types. Use the product names from Settings -> API keys everywhere in code, docs, and support threads: Agent SDK key, Admin API key, and Data import key.

​
Key types

Key typePrefixSend asUse forDo not use for
Agent SDK keypv_live_*X-Pylva-KeyLive agent and app runtimes that send telemetry, sync rules, fetch pricing, and reconcile budgets.Dashboard/admin mutations or import jobs.
Admin API keypv_live_*X-Pylva-KeyServer-side automation that manages project settings such as custom pricing and admin mutations.Frontend code, SDK telemetry, or bulk import jobs.
Data import keypv_cli_*Authorization: Bearer $PYLVA_CLI_KEYCLI/import jobs, currently including cost-source import through POST /api/v1/cost-sources.SDK telemetry or admin mutations.

​
Endpoint families

Agent SDK keys cover the SDK-facing API: Admin API keys cover elevated server-side management: Data import keys cover import/CLI jobs:

​
Permission model

Key prefixes identify the key format, but they do not fully describe permissions. Both Agent SDK keys and Admin API keys use the pv_live_* prefix. Pylva checks the key type/scope on every request and returns 403 WRONG_SCOPE when a valid key is used with the wrong endpoint family. Recommended environment variables:
Key typeEnvironment variable
Agent SDK keyPYLVA_API_KEY
Admin API keyPYLVA_ADMIN_API_KEY
Data import keyPYLVA_CLI_KEY

​
Security

  • Store every key in a backend secret store.
  • Never expose Pylva keys in browser code, mobile apps, prompts, completions, logs, or telemetry metadata.
  • The plaintext key is shown once when created.
  • Pylva stores one-way verification hashes for API keys, not the plaintext key.
  • Rotate or revoke a key from Settings -> API keys if it is exposed.
  • Create Admin API keys sparingly because they can mutate elevated project settings.
For the broader data boundary, see Security And Data Handling.