API Reference

Comprehensive documentation for the dotEnv Cloud API.

The dotEnv Cloud API provides a RESTful interface for managing your environment variables programmatically. This reference documents every endpoint, parameter, and response format.

Base URL

https://api.dotenv.cloud/api/v1

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. Every request should send Accept: application/json, and write requests should send Content-Type: application/json.

Resource Hierarchy & URL Format

Resources follow a strict hierarchy: Organization → Project → Target → Environment, and secrets are stored as an encrypted blob at any level (deepest level wins on merge). New integrations should use the short, recommended path format below; the longer /organizations/{organization}/projects/{project}/… form still works but is deprecated.

/api/v1/{organization}/{project}/{target}/{environment}

{organization} is your organization ULID; project, target, and environment are URL-safe slugs.

Authentication

The dotEnv Cloud API authenticates requests with a Bearer token. Most endpoints use an organization API token with scoped, least-privilege permissions (for example, read-only access to a single project). Create and manage tokens from the dashboard.

Authentication Header

Authorization: Bearer YOUR_API_TOKEN

A missing, invalid, or expired token returns 401 Unauthorized; a valid token that lacks the required permission returns 403 Forbidden. Each endpoint requires a specific token ability (for example project:read or secret:write).

Keep your API tokens secure. Do not share them in public places like GitHub repositories. Tokens can be rotated at any time without touching your secrets.

API Endpoints

Paths below use the short, recommended format. {org} is your organization ULID; {project}, {target}, and {environment} are slugs. Every path is prefixed with the base URL /api/v1.

Identity & Organizations

GET /user Current principal

Returns the user or organization the token authenticates as. Used by the CLI on login.

GET /organizations List organizations

Lists organizations the authenticated principal can access.

POST /organizations Create organization

Creates a new organization; the caller becomes its owner.

GET /organization Organization info

Returns information about the organization the token belongs to.

GET /plans List plans

Returns the global catalog of available plans.

Projects

GET /{org}/projects List projects

Lists all projects in the organization. Requires project:read.

POST /{org}/projects Create project

Creates a new project. Requires project:create; subject to plan limits.

GET /{org}/{project} Get project

Returns a single project by slug. Requires project:read.

PUT/PATCH /{org}/{project} Update project

Updates a project. Requires project:update.

DELETE /{org}/{project} Delete project

Deletes a project. Requires project:delete.

Targets

GET /{org}/{project}/targets List targets

Lists targets (apps or services) in a project. Requires target:read.

POST /{org}/{project}/targets Create target

Creates a new target. Requires target:create.

GET /{org}/{project}/{target} Get target

Returns a single target by slug. Requires target:read.

PUT/PATCH /{org}/{project}/{target} Update target

Updates a target. Requires target:update.

DELETE /{org}/{project}/{target} Delete target

Deletes a target. Requires target:delete.

Environments

GET /{org}/{project}/{target}/environments List environments

Lists environments in a target. Requires environment:read.

POST /{org}/{project}/{target}/environments Create environment

Creates a new environment. Requires environment:create.

GET /{org}/{project}/{target}/{environment} Get environment

Returns a single environment by slug. Requires environment:read.

PUT/PATCH /{org}/{project}/{target}/{environment} Update environment

Updates an environment. Requires environment:update.

DELETE /{org}/{project}/{target}/{environment} Delete environment

Deletes an environment. Requires environment:delete.

Secrets

Secrets are stored and returned as an encrypted .env blob per hierarchy level. Reads resolve from the deepest level provided and can be merged down the hierarchy. Writes target a level via the project, target, and environment slugs in the body.

GET /{org}/{project}/secrets Read project-level secrets

Returns the encrypted secrets blob at project level.

GET /{org}/{project}/{target}/secrets Read target-level secrets

Returns the encrypted secrets blob at target level.

GET /{org}/{project}/{target}/{environment}/secrets Read environment-level secrets

Returns the encrypted secrets blob at environment level.

POST /{org}/secrets/retrieve Retrieve secrets (complex query)

Resolves and optionally merges secrets across levels for a project/target/environment in one call.

POST /{org}/secrets/store Store (upsert) secrets

Upserts the encrypted blob for the resolved level. Requires secret:write; client-managed projects must send key_proof.

POST /{org}/secrets/delete Delete secrets

Clears the secrets blob for a level. Requires secret:write.

Secret Versions

POST /{org}/secrets/versions List version history

Lists backup versions for a level (project/target/environment passed in the body).

GET /{org}/secrets/versions/{version} Get a version

Returns a single version by its numeric id.

POST /{org}/secrets/versions/{version}/restore Restore a version

Restores a level to a previous version.

DELETE /{org}/secrets/versions/{version} Delete a version

Deletes a single backup version.

POST /{org}/secrets/versions/purge Purge version history

Purges backup version history for a level.

Encryption Keys

Server-managed projects return the project key; client-managed projects return only the PBKDF2 key-proof parameters and never the key itself.

GET /{org}/{project}/encryption-key Get key descriptor

Returns the project key (server-managed) or key-proof params (client-managed). Requires key:retrieve.

GET /{org}/{project}/encryption-key/history Key history

Returns the project's encryption key history. Requires key:retrieve.

POST /{org}/{project}/encryption-key/rotate Rotate server-managed key

Rotates the server-managed project key. Requires key:rotate.

POST /{org}/{project}/secrets/rotate-client-keys Rotate client-managed key

Submits secrets re-encrypted under a new client-managed key.

POST /{org}/{project}/secrets/re-encrypt-history/pending List re-encrypt backlog

Returns historical versions still encrypted under a retired client key.

POST /{org}/{project}/secrets/re-encrypt-history Submit re-encrypted history

Submits client-side re-encrypted historical versions.

Interactive API Explorer

Filter by tag:

API Endpoints

POST /api/oauth/token

Exchange authorization code or refresh token for access token

URL


                                    https://api.dotenv.cloud/api/oauth/token

Headers

{
    "Accept": "application/json",
    "Content-Type": "application/json"
}

Request Body

{
    "grant_type": "authorization_code",
    "code": "def50200a1b2c3d4e5f6...",
    "client_id": "01ARZ3NDEKTSV4RRFFQ69G5FAV",
    "code_verifier": "dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk",
    "redirect_uri": "https://app.example.com/callback"
}

200 — Token issued successfully

{
    "access_token": "",
    "token_type": "Bearer",
    "expires_in": 0,
    "refresh_token": ""
}

400 — Invalid request

{
    "error": "invalid_request",
    "error_description": ""
}

401 — Invalid authorization code or refresh token

{
    "error": "invalid_request",
    "error_description": ""
}

curl -X POST \
  'https://api.dotenv.cloud/api/oauth/token' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
    "grant_type": "authorization_code",
    "code": "def50200a1b2c3d4e5f6...",
    "client_id": "01ARZ3NDEKTSV4RRFFQ69G5FAV",
    "code_verifier": "dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk",
    "redirect_uri": "https://app.example.com/callback"
}'

Rate Limiting

The API is rate limited per organization to keep the service stable for everyone. The default limit is 100 requests per minute per organization (falling back to per-IP for unauthenticated requests). The OAuth token endpoint allows 10 requests per minute per IP, and the CLI telemetry endpoint allows 60 per minute per IP. Plans may carry a higher per-minute allowance.

Rate Limit Headers

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 98

If you exceed the rate limit, requests return 429 Too Many Requests with a Retry-After header indicating how many seconds to wait before retrying.