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 Rake task, a Sidekiq worker or a provisioning script.

require "envless/sdk"

token = ENV.fetch("ENVLESS_PROVISIONING_TOKEN")
client = Envless::Client.new(token:)

puts client.me.get[:workspaceId]

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.

require "envless/sdk"

identity = Envless.me.get

puts 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.

require "envless/sdk"

Envless.workspaces.iterate do |workspace|
  reach = workspace[:current] ? "this key" : "needs its own key"

  puts "#{workspace[:slug]} (#{reach})"
end

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:

require "envless/sdk"

passphrase = ENV.fetch("ENVLESS_PASSPHRASE")
workspace_id = Envless.me.get[:workspaceId]
flag = Envless.encrypt_value("true", passphrase, workspace_id)

begin
  Envless.variables.create("billing", "production",
    name: "FLAG", value: flag)
rescue Envless::ApiError => error
  raise unless error.scope_missing?

  puts "This key needs #{error.resource}"
end

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.

require "envless/sdk"

resources = Envless::SCOPE_RESOURCES
read = Envless::SCOPE_LEVELS[:READ]

key = Envless.keys.create(
  name: "ci-deploy",
  scopes: {
    resources[:VARIABLES] => read,
    resources[:VERSIONS] => read
  }
)

puts key[:secret]
puts 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.

require "envless/sdk"

billing = Envless.projects.get("billing")

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

puts key[:secret]

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:

require "envless/sdk"

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

puts replacement[:secret]

Envless.keys.delete(current[:id])

Environment variables#

Those three are the whole list, and an explicit argument always wins over the variable. This is one place the Ruby SDK differs from TypeScript: there, new Envless() reads no environment at all, while Envless::Client.new 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 an ArgumentError before any request is made. The error never echoes the token.