Skip to content

Identity#

Lens Agents treats an agent as an actor in its own right, not as a person's session. That single decision is what makes the audit trail meaningful and what stops a compromised agent from inheriting a human's reach.

Three kinds of principal#

Principal Authenticates with Created by Typical use
User OIDC sign-in through your identity provider Invitation to an organization People: administrators, engineers, reviewers
API token Bearer token api-token create CI jobs, scripts, external agents
Sandbox Platform-issued sandbox token Creating a sandbox Agents running in your cluster

Each is its own subject in the identity model. Each gets its own policy bindings, its own project roles where applicable, and its own rows in the audit trail.

Ask the platform who you are at any time:

curl -fsS -H "Authorization: Bearer $LENS_AGENTS_TOKEN" \
  https://agents.example.com/v1/auth/me

Why sandboxes are principals#

A sandbox does not act as the person who created it. It has its own identity, its own permissions, and its own audit attribution.

The consequences are practical:

  • An agent's actions are never mixed with its creator's in the audit trail. "Who deleted the deployment" has one answer.
  • Revoking an agent's access does not touch anyone's account.
  • An agent cannot reach something merely because an administrator launched it.
  • A sandbox attaches policies directly, with no binding step — it is the subject, so there is nothing to bind it to.

The same reasoning applies to API tokens. A token issued by an administrator is not an administrator.

Organizations and projects#

graph TD
    org[Organization<br><i>tenant boundary</i>]
    org --> proj1[Project]
    org --> proj2[Project]
    user[User] -->|ADMIN| proj1
    user -->|MEMBER| proj2
    token[API token] -->|MEMBER| proj1
    proj1 --> res[Sandboxes · policies · credentials<br>connectors · clusters · AWS connections]

Organizations are the tenant boundary. API tokens, spending limits, org-scoped policies, the audit trail, and billing all live at this level.

Projects are where the work is. Sandboxes, credentials, connectors, clusters, AWS connections, and project policies all belong to exactly one project. A project is the blast radius: an agent in one project cannot see another project's credentials or connectors.

Project members connect the two. An org admin gives each person and API token a role on the projects it needs. Org admins hold ADMIN on every project in their organization.

Role Can
MEMBER Use the project — list and inspect resources, run work within policy.
ADMIN Everything a member can, plus manage the project's resources and exec into its sandboxes.

Removing a person from the organization removes their role on every project in it, so offboarding is one removal, not an audit of every project.

Attribution#

Every audit entry carries the actor type, the actor id, and the display name, alongside the authentication type used. That means the trail distinguishes:

  • A person acting in the admin UI
  • The same person acting through nexusctl
  • The same person acting through a coding agent over MCP
  • An API token that person created, acting in CI
  • A sandbox that person launched, acting on its own

They are five different actors in the log, not one. See Audit trail.