varsafe API

varsafe stores environment variables — database URLs, API keys, signing secrets — encrypted at rest, and hands them to the process that needs them without writing a .env file to disk.

When to use this API

Inject a project environment into a process or pipeline (GET /secrets/inject).
Read one secret value at the moment it is needed (GET /secrets/value), rather than caching a whole environment.
Create, update or delete secrets from automation (POST /secrets, POST /secrets/bulk).
Discover what a credential may do before acting (GET /me/cli, GET /capabilities).

If you are an AI agent, prefer the Model Context Protocol endpoint at POST /mcp over these REST routes: it exposes the same capabilities as typed tools with per-tool scope enforcement and a consent step. See https://docs.varsafe.dev/guides/mcp.

Authentication

Read the security field on each operation — it is derived from what the guards and handlers actually accept, and it is not uniform.

Most routes take an API token (Authorization: Bearer …), created self-serve in the dashboard and scopable to a project, an environment and read-only access. Routes carrying x-varsafe-cli-scopes also accept a CLI grant from the device authorization flow and enforce the listed scopes. Four routes are narrower: GET /me/cli and POST /auth/cli/logout answer only to a CLI grant, because both describe or revoke that grant itself; POST /auth/cli/device/token and GET /auth/cli/device/events authenticate with the device code rather than an account. GET /me accepts a session or a CLI grant but not an API token. The MCP endpoint at POST /mcp uses OAuth 2.1, or an API token, with the scope vocabulary in components.securitySchemes.varsafeMcpOAuth.

Responses

Every operation documents its success body with a JSON Schema under components.schemas, and every failure with the body the server actually sends: ErrorResponse (branch on its code) for REST routes, OAuthErrorResponse and JsonRpcErrorResponse for the MCP transport. The schemas are generated from the same Zod definitions the handlers are type-checked against and that the @varsafe/shared package exports. Objects list the properties sent today; a later release may add one, so ignore properties you do not recognise. Streaming routes (text/event-stream) describe their events in prose.

Scope of this document

This is the programmatic surface: the routes a token, a CLI grant or an agent may call. Dashboard-only and administrative routes are intentionally not described here. The same document is served at https://varsafe.dev/openapi.json and https://api.varsafe.dev/openapi.json.

Version 1.0.0

Base URLhttps://api.varsafe.dev