Authentication

Every request must include an Authorization header carrying a personal access key (ev_sk_...).

Authorization: Bearer ev_sk_xxxxxxxxxxxx

The Bearer prefix is stripped when present and is otherwise optional, so a bare Authorization: ev_sk_... is accepted too. What is not optional is the ev_sk_ prefix: a value that does not start with it is rejected before any database lookup happens.

Generate keys at envless.cloud/dashboard/keys. The full key is shown once. Copy it into your secret store immediately. See Keys for naming, rotation, and revocation.

The same routes are served twice, once at the root and once under /v1, so https://api.envless.cloud/workspace and https://api.envless.cloud/v1/workspace are the same endpoint.

The key is the whole check#

That is structural rather than an omission. Both of those checks are answered by a human at a keyboard: one reads a code out of an inbox, the other reads it off a phone. An ev_sk_ key is a pre-authorized machine credential running unattended in CI, so there is nobody to ask, and gating the surface would break every consumer that uses it. The gates sit on minting instead: creating a key in the dashboard, rotating one, deleting one, and changing its scopes or allowlist all require step-up, and the account that does the minting can be second-factor protected. The workspace requirement above is the one gate that reaches a key already in use, and it manages that by asking a question about the owner's account rather than about the request.

What follows from that is the control model. A key's blast radius is its scopes and its project allowlist, nothing else, and the only revocation is deletion or rotation from the dashboard. Scope keys to the minimum, keep one key per consumer so a single revocation is targeted, and treat a leaked key as fully live until the moment somebody deletes it.

What a key grants#

Every key belongs to a single workspace and carries a scope per resource. Each resource is granted one of three levels (none, read, or write), and write implies read. There are eleven resources:

A resource left at none returns 403 on every route that names it. Some routes require two scopes at once, and both are checked before the handler runs: every duplicate route also needs variables:write (a product duplicate additionally needs projects:write), version rollback and entry re-encryption need variables:write, reading a version or its entries needs variables:read, and GET /products/:slug/projects needs projects:read.

A key can additionally be pinned to an allowlist of projects. Leave it empty for the whole workspace, or list specific project IDs (not slugs) to fence the key in.

What the fence narrows is environments, variables, versions and the project reads: GET /projects and GET /products/{slug}/projects return only the fenced projects, and any route resolving a project outside the fence is 403 auth.key_project_restricted.

The workspace-wide surfaces are not narrowed, they are closed. Each of these refuses a fenced key outright with 403 auth.key_project_restricted, whatever scope the key holds:

POST /keys is the one key route a fenced key keeps. There projectIds becomes mandatory and must be a non-empty subset of the caller's own fence, so a fenced key can mint narrower keys but can never read back the list it just added to.

Everything else at workspace level is untouched by the fence, because none of it has a project dimension to narrow: GET /me, the workspace and domain routes, GET /workspaces, all of members, invites and roles, and the product reads GET /products, GET /products/{slug} and GET /products/{slug}/access.

Grant the narrowest scopes that get the job done. A CI key that only pulls ciphertext needs nothing beyond variables:read: the variables routes take the project and environment slugs in the path and resolve them internally, so no projects or environments scope is involved. Add workspace:read only if the client has to resolve the workspace ID itself. @goenvless/env/edge is the common case: its load({ token, project, environment, passphrase }) calls GET /workspace first whenever no workspaceId and no key were passed, because the passphrase is derived against the workspace ID. Pass workspaceId or a raw key and that call disappears, leaving variables:read as the only scope the edge loader needs.

Examples#

GET /me is the only endpoint that requires no scope at all, which makes it the way to prove a key is live before you debug anything else. It returns the owning user, the bound workspaceId and the key's own id, name and createdAt.

curl https://api.envless.cloud/me \
    -H "Authorization: Bearer ev_sk_xxxxxxxxxxxx"

const res = await fetch('https://api.envless.cloud/me', {
    headers: { Authorization: `Bearer ${process.env.ENVLESS_TOKEN}` },
});
const { data } = await res.json();

import os, requests
res = requests.get(
    "https://api.envless.cloud/me",
    headers={"Authorization": f"Bearer {os.environ['ENVLESS_TOKEN']}"},
)
data = res.json()["data"]

require "net/http"
require "json"

uri = URI("https://api.envless.cloud/me")
headers = {"Authorization" => "Bearer #{ENV.fetch("ENVLESS_TOKEN")}"}
data = JSON.parse(Net::HTTP.get_response(uri, headers).body)["data"]

$context = stream_context_create(['http' => [
    'header' => 'Authorization: Bearer ' . getenv('ENVLESS_TOKEN'),
]]);
$data = json_decode(file_get_contents('https://api.envless.cloud/me', false, $context), true)['data'];

req, _ := http.NewRequest("GET", "https://api.envless.cloud/me", nil)
req.Header.Set("Authorization", "Bearer " + os.Getenv("ENVLESS_TOKEN"))
res, _ := http.DefaultClient.Do(req)

The TypeScript, Python, Ruby and PHP SDKs send the header for you, and this whole call is envless.me.get() in the first two, Envless.me.get in Ruby and $envless->me->get() in PHP.

Every response is the same envelope: success, code, message, error, data and _req. On a failure error.code carries the machine-readable string from the tables below, and data is null.

Failure modes#

Last used#

Each key records a single lastUsedAt timestamp, shown in the dashboard, and nothing else. The write is throttled: a key that was already touched within the last 60 seconds is not written again, and the update is fire-and-forget so a failed write never fails the request. There is no per-key request counter and no per-request log to read back, so treat lastUsedAt as a liveness signal for finding dormant keys to rotate, not as usage accounting.

Keys change underneath you#

Two things change what a key can do without anyone touching the key. A plan change is not one of them: keys work on every plan, Free included, so a downgrade never deactivates a key, though a project the downgrade locks still answers 402 to it (see Plans and billing).

A role change re-clamps the scopes of every key its owner holds in that workspace. Scopes are clamped to the owner's workspace permissions at creation time and again whenever the owner's role, or that role's permission set, changes. A key can silently drop from write to read, or to none, so read scopes back rather than assuming the key still holds what you asked for.

A workspace two factor requirement stops every key whose owner has not enrolled. Turning the requirement on is an admin action taken in the dashboard, and it lands on the keys immediately: every request returns 403 auth.workspace_two_factor_required until that owner enables two factor or the requirement comes back off. The key's record is not changed, so nothing in GET /keys looks different. If a pipeline stops the same day someone tightened workspace settings, this is the first thing to check.