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, a Celery worker or a provisioning script.

import os

from envless import Envless

envless = Envless(os.environ['ENVLESS_PROVISIONING_TOKEN'])

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.

from envless import envless

identity = envless.me.get()

print(identity['workspaceId'])

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 set to True marks the bound one.

from envless import envless

for workspace in envless.workspaces.list_all():
    print(workspace['slug'], '(this key)' if workspace['current'] else '(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 os

from envless import EnvlessApiError, encrypt_value, envless

workspace_id = envless.me.get()['workspaceId']
ciphertext = encrypt_value('true', os.environ['ENVLESS_PASSPHRASE'], workspace_id)

try:
    envless.variables.create('billing', 'production', {'name': 'FLAG', 'value': ciphertext})
except EnvlessApiError as error:
    if not error.is_scope_missing:
        raise

    print(f'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.

from envless import SCOPE_LEVELS, SCOPE_RESOURCES, envless

key = envless.keys.create(
    {
        'name': 'ci-deploy',
        'scopes': {
            SCOPE_RESOURCES.VARIABLES: SCOPE_LEVELS.READ,
            SCOPE_RESOURCES.VERSIONS: SCOPE_LEVELS.READ,
        },
    }
)

print(key['secret'])
print(key['scopes'])

secret is shown once and is unrecoverable, and scopes is 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.

from envless import envless

billing = envless.projects.get('billing')

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

An empty projectIds list 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.list_projects() 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.

from envless import envless

current = envless.keys.get('0191f3c2-8a71-7c3e-9b2d-4f5a6c7d8e90')
replacement = envless.keys.create(
    {
        'name': 'ci-deploy-2026-10',
        'scopes': current['scopes'],
        'projectIds': current['projectIds'],
    }
)

print(replacement['secret'])

Deploy replacement['secret'] to your runner and confirm it works. Only then retire the old key:

from envless import envless

envless.keys.delete('0191f3c2-8a71-7c3e-9b2d-4f5a6c7d8e90')

Environment variables#

Those three are the whole list, and an explicit argument always wins over the variable. This is one place the Python SDK differs from TypeScript: there, new Envless() reads no environment at all, while Envless() in Python reads both variables whenever you leave token or base_url out. Passing disable_update_notice=True silences the notice without an environment variable, and the check is skipped whenever stdout is not a terminal.

A token is trimmed of surrounding whitespace, the way an HTTP header would be, and a token with a control character or anything outside visible ASCII is refused with a ValueError before any request is made. The error never echoes the token.