Skip to content

Organizations, teams, and projects#

Three levels, each with a clear job: the organization is the tenant boundary and the governance ceiling, projects are the blast radius, and teams connect people to projects.

Create the hierarchy#

curl -fsS -X POST \
  -H "Authorization: Bearer $LENS_AGENTS_TOKEN" \
  -H "Content-Type: application/json" \
  https://agents.example.com/v1/orgs \
  -d '{"name": "acme", "displayName": "Acme Corporation"}'

curl -fsS -X POST \
  -H "Authorization: Bearer $LENS_AGENTS_TOKEN" \
  -H "Content-Type: application/json" \
  https://agents.example.com/v1/orgs/$ORG_ID/projects \
  -d '{"name": "production", "displayName": "Production"}'

curl -fsS -X POST \
  -H "Authorization: Bearer $LENS_AGENTS_TOKEN" \
  -H "Content-Type: application/json" \
  https://agents.example.com/v1/orgs/$ORG_ID/teams \
  -d '{"name": "platform", "displayName": "Platform Team"}'

Set up an org called acme ("Acme Corporation") with a production
project and a platform team. Give the platform team ADMIN on
production.

# Organization — the tenant boundary
nexusctl org create --name acme --display-name "Acme Corporation"

# Project — where sandboxes and connections live
nexusctl project create --org acme --name production --display-name "Production"

# Team — how people and tokens reach projects
nexusctl team create --org acme --name platform --display-name "Platform Team"
nexusctl team set-access platform --org acme --project production --role ADMIN

Slugs are lowercase letters, digits, and dashes. They are what you type in every later command, so pick names that will still make sense in a year.

Organizations#

The tenant boundary. API tokens, spending limits, the audit trail, org-scoped policies, and billing all live here.

Invite people#

curl -fsS -X POST \
  -H "Authorization: Bearer $LENS_AGENTS_TOKEN" \
  -H "Content-Type: application/json" \
  https://agents.example.com/v1/orgs/$ORG_ID/invitations \
  -d '{"email": "alex@example.com", "role": "member"}'

Invite alex@example.com to the acme org as a member.

nexusctl invitation create --org acme --email alex@example.com --role member
nexusctl invitation list --org acme

Invitees see and act on their own invitations:

nexusctl invitation list-mine
nexusctl invitation accept <invitation-uuid>

Revoke a pending invitation with nexusctl invitation revoke <invitation-uuid> --org acme.

Org policies are a ceiling#

This is the most important thing on this page.

An org-scoped policy is not merely a default that projects inherit. It is an upper bound. When the platform resolves a sandbox's effective policy, anything a project binding grants beyond what the org policy permits is clipped.

graph TD
    org[Org policy<br><i>the ceiling</i>] --> merge[Effective policy]
    proj[Project policies and bindings] --> merge
    sb[Sandbox-attached policies] --> merge
    merge --> clip{Clip to org ceiling}
    clip --> eff[What the agent can actually do]

That gives a platform team a real control: write one org policy naming the domains, connectors, and inference providers the organization permits at all, and no project — however it is configured, by whoever configures it — can exceed it.

Clipping is silent, so audit it:

nexusctl policy-binding list-drift --org acme

Every drift entry is a project team that believes it granted something the organization does not allow. Review it on a schedule. See Policy bindings.

Projects#

Where the work happens. Sandboxes, credentials, connectors, clusters, AWS connections, and project policies each belong to exactly one project.

A project is the blast radius. An agent in staging cannot see production's credentials or connectors, whatever its policy says — those resources are not in its scope to name.

nexusctl project list --org acme
nexusctl project describe production --org acme

describe shows a project's clusters, policies, AWS connections, and resource counts in one view.

How to split projects#

Use the boundary that matches your real blast radius, usually one of:

  • By environment — production, staging. Different credentials, different limits, different people.
  • By team — each team owns its project end to end.
  • By risk — separate the agents that may write from those that may only read.

Prefer more projects to fewer. A project is cheap; a credential shared across two blast radii is not.

Teams#

Teams connect principals to projects. Both people and API tokens can be members.

curl -fsS -X POST \
  -H "Authorization: Bearer $LENS_AGENTS_TOKEN" \
  -H "Content-Type: application/json" \
  https://agents.example.com/v1/teams/$TEAM_ID/members \
  -d '{"userId": "alex@example.com"}'

curl -fsS -X PUT \
  -H "Authorization: Bearer $LENS_AGENTS_TOKEN" \
  -H "Content-Type: application/json" \
  https://agents.example.com/v1/teams/$TEAM_ID/project-access \
  -d '{"projectId": "'"$PROJECT_ID"'", "role": "ADMIN"}'

Add alex@example.com and the ci-deploy token to the platform team.
Give the team ADMIN on production and MEMBER on staging.

nexusctl team add-member platform --org acme --user alex@example.com
nexusctl team add-member platform --org acme --api-token ci-deploy

nexusctl team set-access platform --org acme --project production --role ADMIN
nexusctl team set-access platform --org acme --project staging --role MEMBER
Role Can
MEMBER Use the project — list and inspect resources, run work within policy.
ADMIN Everything a member can, plus manage project resources and exec into sandboxes.

sandbox exec requires project ADMIN. Getting a shell inside a running agent is an administrative action, not an everyday one.

Grant access through teams rather than to individuals. Offboarding then becomes one membership removal instead of an audit of every project.

nexusctl team remove-access platform --org acme --project staging
nexusctl team remove-member platform --org acme <membership-uuid>

Example setup#

Resource Example
Org policy org-ceiling — every domain, connector, and provider the company permits at all
Projects production, staging
Teams platform (ADMIN on both), app-eng (MEMBER on staging)
Org spending limit Monthly, matching the agreed budget
Drift review policy-binding list-drift --org acme, monthly
  • Identity — the principals in this hierarchy
  • Policies — org and project scope
  • Policy bindings — the ceiling and drift in detail
  • SSO — authenticating members against your directory