Authentication

The SDK authenticates with an API key and nothing else. There is no login flow, no device authorisation, no browser round-trip, and no dependency on the CLI. Pass a key, or set ENVLESS_TOKEN, and you are done, which is exactly what makes it usable from CI, a cron job, a Lambda or a provisioning script.

import { createClient } from '@goenvless/sdk'

const envless = createClient({ token: 'ev_sk_...' })

A key is bound to one workspace#

A key is bound to a single workspace at creation time, permanently. The workspace comes from the key, never from the request, so there is no header or argument that points a key at a different one.

const identity = await envless.me.get()

identity.workspaceId   // the only workspace this key will ever touch

envless.workspaces.list() is the single exception to that boundary: it resolves the key owner's memberships, so it can name workspaces the key cannot act on. current: true marks the bound one.

const all = await envless.workspaces.listAll()

for (const workspace of all) {
    console.log(workspace.slug, workspace.current ? '(this key)' : '(needs its own key)')
}

Scopes#

Every endpoint except me.get() requires a scope. A scope is a resource and a level:

A missing scope is 403 auth.scope_missing, and error.resource names exactly what was needed:

import { EnvlessApiError } from '@goenvless/sdk'

try {
    await envless.variables.create('billing', 'production', { name: 'A', value: ciphertext })
}

catch (error) {
    if (error instanceof EnvlessApiError && error.isScopeMissing) {
        console.error(`This key needs ${error.resource}`)
    }
}

Some methods need two scopes because they touch two resources. versions.rollback rewrites variables, so it needs versions:write and variables:write. Each method page lists its own requirement.

Scopes are clamped twice#

A key never carries more authority than the person who created it.

const key = await envless.keys.create({
    name: 'ci-deploy',
    scopes: { variables: 'read', versions: 'read' }
})

console.log(key.secret)   // shown once, unrecoverable
console.log(key.scopes)   // what you were actually granted

Project fences#

A key can be fenced to specific projects with projectIds. Any request touching a project outside the fence fails with 403 auth.key_project_restricted.

const key = await envless.keys.create({
    name: 'billing-only',
    scopes: { variables: 'read' },
    projectIds: [billing.id]
})

An empty projectIds array means the whole workspace. Private products add a second, independent gate: the key owner also needs a grant on the product, or the call is 403 auth.product_restricted.

The fence is not only a filter. Several workspace-level surfaces are closed to a fenced key outright, whatever scope it holds, because none of them can be expressed as a subset of projects:

The same refusal applies to every webhooks method, to every products write (create, update, delete, duplicate), to both products.access writes (grant, revoke), and to projects.create() and projects.duplicate(), since a newly created project could not be covered by the fence.

What a fenced key still reads at workspace level is me, workspace, workspaces, workspace.domain, members, invites, roles, and the product reads (products.list(), products.get(), products.access.list()). Those carry no project dimension, so there is nothing for the fence to narrow. projects.list() and products.listProjects() are narrowed rather than closed: they return only the fenced projects.

Rotation#

There is deliberately no rotate method for API keys. Rotation is create, cut over, delete. Copy projectIds along with scopes: leave it out and the replacement reaches the whole workspace, not just the projects the old key was fenced to.

const replacement = await envless.keys.create({
    name: 'ci-deploy-2026-07',
    scopes: current.scopes,
    projectIds: current.projectIds
})

// deploy replacement.secret to your runner, confirm it works, then

await envless.keys.delete(current.id)

Environment variables#

Those three are the whole list. The first two are read inside createClient() alone, so new Envless({ token }) skips them and takes its token and base URL from the arguments only. ENVLESS_DISABLE_UPDATE_NOTICE is read by the transport, which every client goes through, so new Envless(...) reads it too. Passing disableUpdateNotice: true does the same thing without an environment variable.

All three reads are guarded on process existing, so in a Worker none of them happen. The update notice is skipped there for a second reason as well: it only ever prints when stdout is a TTY.