Skip to content

Identity & Authentication#

Lens Agents uses two identity models: user identity for desktop tools and agent identity for external and managed agents. Every action on the platform is attributed to a specific identity in the audit trail.

Two identity models#

User identity (OIDC)#

Desktop AI tools (Claude Desktop, Cursor, Claude Code, ChatGPT, Copilot) authenticate via the user's SSO credentials. The user signs in through their identity provider, and the tool operates under the user's identity.

Property Detail
Protocol OIDC (OpenID Connect)
Credential Session token issued after SSO authentication
Scope User's organization membership and team assignments
Audit Actions attributed to the user's email and name
Lifecycle Active as long as the user's IdP account is active

User identity is the right model when a human is directly using an AI tool. The audit trail shows "Alice ran kubectl get pods" rather than "Agent-47 ran kubectl get pods."

Agent identity (agent tokens)#

External and managed agents authenticate via dedicated agent tokens. Each agent is a first-class principal — not tied to any human user.

Property Detail
Token format Opaque bearer token with a platform-specific prefix
Scope Single organization, assigned to a team with project-level access
Audit Actions attributed to the agent's name and token ID
Lifecycle Active until explicitly revoked or the agent is deleted

Agent identity is the right model when the agent operates autonomously — scheduled tasks, heartbeat monitoring, background processes — where no human is actively driving the interaction.

Authentication Flow#

Token type routing#

The platform inspects each incoming credential to determine the identity type:

  • Agent tokens — opaque bearer tokens issued for a specific agent. Validated against the platform's token store.
  • User JWTs — standard OIDC identity tokens issued by the organization's identity provider. Validated against the IdP's signing keys.

Both token types route to the same endpoints; the platform handles authorization uniformly from there.

SSO flow for desktop tools#

  1. User configures their desktop tool with the Lens Agents MCP endpoint
  2. On first connection, the tool triggers an SSO redirect to the configured identity provider
  3. User authenticates (including MFA if configured at the IdP)
  4. Identity provider returns a token to Lens Agents
  5. Lens Agents validates the token and establishes the user's session
  6. The desktop tool receives a session token and uses it for subsequent requests
  7. Token refresh is automatic — the user does not need to re-authenticate unless the refresh token expires

Agent token flow#

  1. An administrator provisions an agent token scoped to a specific team and set of projects (managed agents are provisioned automatically at creation time).
  2. The agent's MCP client presents the token as a bearer credential on each connection.
  3. The platform validates the token and resolves the agent's team, project, and policy scope for every request.

Token scope and team membership#

Both identity types are scoped through the same team and project hierarchy:

  • Users belong to one or more teams, each with project-level access grants
  • Agent tokens are assigned to a team with the same project-level access grants
  • Project access determines which infrastructure connections (Kubernetes clusters, AWS accounts, GitHub repos) the identity can use

A user on the "Platform Engineering" team with access to the "Production" project can reach production clusters. An agent token on the same team with the same project access can reach the same clusters. The policy engine governs what actions are allowed in both cases.

Managed agent identity#

Managed agents get their identity automatically:

  • A dedicated token is created at agent creation — no manual token management
  • The token is assigned to the team selected during creation
  • The token inherits the team's project access
  • If the agent's team membership changes, the token's access changes with it

You never need to create, rotate, or manage tokens for managed agents.

Audit Attribution#

Every action is attributed to the identity that performed it:

Identity type Audit record shows
User User email, name, action, target resource, timestamp
Agent Agent name, token ID, action, target resource, timestamp
Managed agent Agent name, auto-provisioned token ID, action, target, timestamp
Subagent Subagent name, own token ID, action, target, timestamp

For managed agents executing scheduled tasks or heartbeat checks, the audit trail records the invocation mode (chat, heartbeat, cron, subagent) alongside the agent's identity.

For Slack interactions in team mode, messages from multiple users are attributed to the sending user, while the agent's actions are attributed to the agent.