❯envpilot
featurespricing❯docsblogchangelogwishlistfaq
sign-inget-started
// documentation
Start Here
  • Quickstart
  • Core concepts
  • Architecture: the machine surfaces
Platform
  • Data model
  • Variables
  • Secret files
  • Shared Accounts
  • Secret Sharing Links
  • Diagrams in documentation
  • Sharing documentation
  • Roles & permissions
  • Requests & approvals
  • Protected environments
  • Rotation & expiry
  • Security
Plans & Limits
  • Plans & Limits
  • Rate limits
CLI
  • CLI overview
  • Authentication & accounts
  • Linking projects
  • Pull & push
  • Running commands with secrets
  • Single secrets
  • Requests
  • Secret files
  • Command reference
  • CLI in CI & troubleshooting
VS Code
  • VS Code overview
  • Linking & sync
  • Protection
  • Editor features
  • Commands
  • Settings
  • Troubleshooting
JetBrains
  • JetBrains overview
  • Linking & sync
  • Protection
  • Troubleshooting
GitHub Action
  • GitHub Action overview
  • Inputs & outputs
  • Secret files in CI
  • Recipes
  • Action security
Docker
  • Docker overview
  • Build time
  • Runtime
  • Docker Compose
  • Docker reference
API Reference
  • API overview
  • API Quickstart
  • Authentication
  • Errors
  • Organization
  • Projects
  • Variables
  • Shared accounts
  • Secret files
MCP Server
  • MCP overview
  • MCP setup
  • Connecting a client
  • Tools
  • Agent requests
  • API keys (legacy)
Web Dashboard
  • Dashboard overview
  • Working in a project
  • Organization administration
Integrations
  • Slack & Discord Notifications
Guides
  • How to Share Environment Variables Securely
  • Next.js Environment Variables Best Practices
  • Android keystore in CI
  • Giving an agent secrets safely

// resources

  • github
  • npm
  • vs code marketplace
  • jetbrains marketplace
Start HerePlatformPlans & LimitsCLIVS CodeJetBrainsGitHub ActionDockerAPI ReferenceMCP ServerWeb DashboardIntegrationsGuides
❯envpilot

Encrypted environment variables for teams that live in the terminal. No .env files, no secrets in Slack.

$npm install -g @envpilot/cli

// product

  • Features
  • Pricing
  • Changelog
  • Wishlist

// resources

  • Getting Started
  • CLI Reference
  • VS Code Extension
  • Security

// compare

  • vs Doppler
  • vs Infisical
  • vs .env files

// support

  • FAQ
  • Support
  • Contact
  • Docs
  • Status

// legal

  • Privacy Policy
  • Terms of Service

© 2026 Envpilot · Built at Syntax Lab Technology · Abdul Rafay

ENVPILOT

❯envpilot
featurespricing❯docsblogchangelogwishlistfaq
sign-inget-started
// documentation
Start Here
  • Quickstart
  • Core concepts
  • Architecture: the machine surfaces
Platform
  • Data model
  • Variables
  • Secret files
  • Shared Accounts
  • Secret Sharing Links
  • Diagrams in documentation
  • Sharing documentation
  • Roles & permissions
  • Requests & approvals
  • Protected environments
  • Rotation & expiry
  • Security
Plans & Limits
  • Plans & Limits
  • Rate limits
CLI
  • CLI overview
  • Authentication & accounts
  • Linking projects
  • Pull & push
  • Running commands with secrets
  • Single secrets
  • Requests
  • Secret files
  • Command reference
  • CLI in CI & troubleshooting
VS Code
  • VS Code overview
  • Linking & sync
  • Protection
  • Editor features
  • Commands
  • Settings
  • Troubleshooting
JetBrains
  • JetBrains overview
  • Linking & sync
  • Protection
  • Troubleshooting
GitHub Action
  • GitHub Action overview
  • Inputs & outputs
  • Secret files in CI
  • Recipes
  • Action security
Docker
  • Docker overview
  • Build time
  • Runtime
  • Docker Compose
  • Docker reference
API Reference
  • API overview
  • API Quickstart
  • Authentication
  • Errors
  • Organization
  • Projects
  • Variables
  • Shared accounts
  • Secret files
MCP Server
  • MCP overview
  • MCP setup
  • Connecting a client
  • Tools
  • Agent requests
  • API keys (legacy)
Web Dashboard
  • Dashboard overview
  • Working in a project
  • Organization administration
Integrations
  • Slack & Discord Notifications
Guides
  • How to Share Environment Variables Securely
  • Next.js Environment Variables Best Practices
  • Android keystore in CI
  • Giving an agent secrets safely

// resources

  • github
  • npm
  • vs code marketplace
  • jetbrains marketplace
Start HerePlatformPlans & LimitsCLIVS CodeJetBrainsGitHub ActionDockerAPI ReferenceMCP ServerWeb DashboardIntegrationsGuides
❯envpilot

Encrypted environment variables for teams that live in the terminal. No .env files, no secrets in Slack.

$npm install -g @envpilot/cli

// product

  • Features
  • Pricing
  • Changelog
  • Wishlist

// resources

  • Getting Started
  • CLI Reference
  • VS Code Extension
  • Security

// compare

  • vs Doppler
  • vs Infisical
  • vs .env files

// support

  • FAQ
  • Support
  • Contact
  • Docs
  • Status

// legal

  • Privacy Policy
  • Terms of Service

© 2026 Envpilot · Built at Syntax Lab Technology · Abdul Rafay

ENVPILOT

// documentation
Start Here
  • Quickstart
  • Core concepts
  • Architecture: the machine surfaces
Platform
  • Data model
  • Variables
  • Secret files
  • Shared Accounts
  • Secret Sharing Links
  • Diagrams in documentation
  • Sharing documentation
  • Roles & permissions
  • Requests & approvals
  • Protected environments
  • Rotation & expiry
  • Security
Plans & Limits
  • Plans & Limits
  • Rate limits
CLI
  • CLI overview
  • Authentication & accounts
  • Linking projects
  • Pull & push
  • Running commands with secrets
  • Single secrets
  • Requests
  • Secret files
  • Command reference
  • CLI in CI & troubleshooting
VS Code
  • VS Code overview
  • Linking & sync
  • Protection
  • Editor features
  • Commands
  • Settings
  • Troubleshooting
JetBrains
  • JetBrains overview
  • Linking & sync
  • Protection
  • Troubleshooting
GitHub Action
  • GitHub Action overview
  • Inputs & outputs
  • Secret files in CI
  • Recipes
  • Action security
Docker
  • Docker overview
  • Build time
  • Runtime
  • Docker Compose
  • Docker reference
API Reference
  • API overview
  • API Quickstart
  • Authentication
  • Errors
  • Organization
  • Projects
  • Variables
  • Shared accounts
  • Secret files
MCP Server
  • MCP overview
  • MCP setup
  • Connecting a client
  • Tools
  • Agent requests
  • API keys (legacy)
Web Dashboard
  • Dashboard overview
  • Working in a project
  • Organization administration
Integrations
  • Slack & Discord Notifications
Guides
  • How to Share Environment Variables Securely
  • Next.js Environment Variables Best Practices
  • Android keystore in CI
  • Giving an agent secrets safely

// resources

  • github
  • npm
  • vs code marketplace
  • jetbrains marketplace
Start HerePlatformPlans & LimitsCLIVS CodeJetBrainsGitHub ActionDockerAPI ReferenceMCP ServerWeb DashboardIntegrationsGuides
API overviewAPI QuickstartAuthenticationErrorsOrganizationProjectsVariablesShared accountsSecret files
docs/API Reference

Authentication

The API key model — scoping, surfaces, revocation, audit, and the fail-loud contract shared by REST, the GitHub Action and the Docker image.

open in claudeopen in chatgptopen in cursor

Authentication

The REST API, the GitHub Action and the Docker image all authenticate with the same key system and call the same underlying Convex actions — one enforcement core, three faces. Nothing about auth, scoping, or auditing is re-implemented per surface. The MCP server is different: it accepts only your Envpilot sign-in (OAuth), never a key.

Key model#

  • A new key is generated as envpk_... and shown exactly once, at creation time.
  • Envpilot stores only a SHA-256 hash of the key, never the plaintext. If you lose a key, there's no way to recover it — revoke it and issue a new one.
  • Every key is scoped along three dimensions: projects (all or a specific list), environments (all or a specific list), and resources (variables, accounts, projects, and optionally files). A request for anything outside a key's scope is treated as if it doesn't exist.
  • Every key also declares its surfaces — which faces it may authenticate on: rest_api, github_action, docker. All of them route through one enforcement core (_authorizeRequest); see Architecture. Older keys may still list mcp_server; the MCP server ignores keys.
  • Keys can optionally have an expiry date (expiresAt). An expired key returns the same uniform "invalid or revoked" error as a bad or revoked key — the API never tells a caller why a key stopped working.

The files resource is never granted by default

Secret files are the highest-value material a key can read — a signing keystore is not recoverable by rotating a string. So files is an explicit opt-in when minting a key, never included by a "select all" default, and every file-content read is audited individually.

Machine credentials never write secrets#

Every API key — REST API, GitHub Action or Docker image — is fundamentally read-only. No API key can create, edit, or delete a variable's value. The blast radius of a leaked key is bounded to reads within its scope, never a silent change to what a deploy pulls. The MCP server does not accept keys: it acts as the signed-in person, under their role.

This is the trust model in one line: keys read, people write. Keys can no longer file variable requests; that path was removed with API-key access to the MCP server.

Revocation is immediate#

Revoking a key from the dashboard takes effect on the next request — there is no grace period and no cache to wait out. Every request re-checks the key's status (valid, scoped, not expired, not revoked, plan still entitled) before doing any work.

Why 401 vs 403 vs 404 are deliberately uninformative#

  • 401 covers every reason a key doesn't work — missing, malformed, invalid, expired, or revoked — as one message. This stops an attacker from using error responses to fingerprint why a specific key failed.
  • 403 means the key is valid but the org's plan or the key's own resource scope doesn't cover this call (e.g. a variables-only key hitting /accounts, or the org isn't on a plan with public_api/mcp_server enabled).
  • 404 means the target doesn't exist or exists but is outside the key's scope — both return the same 404. A key is never allowed to confirm the existence of a project it can't see.

Fail-loud, never partial#

If any part of a variable pull can't be completed safely, the whole request fails instead of returning something silently incomplete:

  • No partial pulls. If vault decryption fails for any variable in the response, the request aborts with 503 rather than returning the variables that did decrypt and omitting the ones that didn't.
  • No sentinel values. A variable that fails to decrypt is never represented as an empty string, null, or placeholder — that would look like a real (wrong) value to a deploy script.
  • No silent truncation. A project with more than 1000 matching variables returns 422 rather than a truncated list that looks complete but isn't.

Audit trail#

Every value pull with a key is logged — which key, which project/environment, which filters were used, and the source (public-api, or cicd for the GitHub Action). MCP has no key: its reads and writes are logged against the signed-in person, and value reads are marked via: oauth with the client that made them. Metadata-only reads (key names without values) are not audited individually to avoid log noise, since they carry no secret exposure.

Every denied request is also logged, including:

  • Reuse of a revoked key
  • A request outside a key's scope
  • A tier/plan gate rejection after a downgrade

Revoked-key reuse is treated as the highest-signal event in this set — it's the strongest indicator of a leaked key still being used after the team responded.

Rate limiting#

Rate limits are enforced per key with a token-bucket limiter — 120/min for metadata reads, 30/min for value pulls (see API Reference for the full table). Requests using a key hash that doesn't match anything on file are rate-limited separately, per hash, to slow down brute-force key guessing.

Why there's no CORS#

The API and MCP endpoint deliberately do not send CORS headers, so browsers refuse cross-origin requests to them. API keys are bearer credentials with broad read access to your secrets — they must never be shipped in client-side JavaScript where anyone with dev tools open could read them out of a network request. If you need secrets in a browser context, that's a product decision to make deliberately, not something the public API should make easy by accident.

CI runners are ephemeral#

GitHub-hosted (and most self-hosted) runners are torn down after each job. A pulled variable only exists in that job's process environment for the duration of the run — it isn't persisted anywhere by Envpilot's side, and the GitHub Action additionally masks every value in the job log before it's exported.

Tier downgrades#

If an organization's plan is downgraded below the tier that grants public_api/mcp_server, existing keys aren't proactively deleted — the same per-request gate check simply starts returning 403 on the next call. There's no background sweep to race and no window where a downgraded org's keys keep working past the next request.

Limits#

  • Scope is immutable. Projects, environments, resources and surfaces are fixed at creation.
  • The plaintext is shown once. There is no recovery and no rotate-in-place — revoke and re-issue.
  • Org-wide key creation is owner-only; team leads can mint keys limited to specific projects.
  • Pro plan required (public_api / mcp_server), re-checked per request.
  • Keys are bearer credentials with no IP allowlist and no per-key CORS exemption.
← api referenceAPI Quickstart
api reference →Errors

// on this page

  • Key model
  • Machine credentials never write secrets
  • Revocation is immediate
  • Why 401 vs 403 vs 404 are deliberately uninformative
  • Fail-loud, never partial
  • Audit trail
  • Rate limiting
  • Why there's no CORS
  • CI runners are ephemeral
  • Tier downgrades
  • Limits