Managing Teams & Access

As a manager, you control who has access to Nexus in your organization, what they can do, and which projects they can access. This guide covers how to add team members, assign roles, manage permissions, and remove access when needed.

Team Management

Add Team Members

Invite users to your organization and assign roles.

Add members →

Manage Roles

Assign User, Auditor, or Manager roles to control permissions.

Manage roles →

Control Access

Set up API keys, classification ceilings, and project access.

Control access →

Remove Users

Suspend or remove team members and revoke their access.

Remove access →

---

Understanding Roles and Permissions

Nexus has three roles that control what team members can do: User, Auditor, and Manager. Roles are hierarchical, meaning each higher role includes all the permissions of the roles below it.

User: Self-service team members who can create API keys and view usage for their projects. Users can make AI requests, monitor their own spending, and manage their own credentials. They cannot access audit logs or manage other team members.

Auditor: Everything a User can do, plus read-only access to audit logs including all historical audit data for their organization. Auditors can view compliance records, review request history, and download audit verification proofs. They cannot modify settings, manage users, or access full request traces. Important: When you promote someone to Auditor, they immediately gain visibility into the complete audit history, which may include sensitive historical activity such as past security incidents, terminated employees’ actions, or compliance investigations.

Manager (highest permissions): Full administrative control over organizations, projects, members, and settings. Managers can add or remove team members, assign roles, configure budgets and classification rules, and access all data within their managed scopes.

When you add a team member, you assign them a role at the organization or project level. Their access is automatically scoped to the projects within that organization, ensuring that team members can only see data relevant to their work.

For detailed information about what each role can and cannot do, see the FAQ and Features Overview.

Why it matters

Assigning the right role ensures team members have the access they need without exposing them to data or controls beyond their responsibilities. This follows the principle of least privilege.

Adding Team Members

Currently, adding team members to your organization requires using the Nexus CLI. A web-based UI for user management is planned for a future release.

Important: The Nexus CLI commands shown below must be run by someone with access to your Nexus deployment’s infrastructure (typically your platform administrator or DevOps team). Simply running these commands in your local terminal will not work unless you have the Nexus CLI installed and configured with the appropriate credentials and access to your deployment.

If you need to add team members and don’t have CLI access yourself, please coordinate with your platform administrator or technical team who can run these commands on your behalf.

Creating User Accounts

Use the Nexus CLI to create a user account and assign them to your organization:

# Create a user and assign them to an organization
nexus auth users create \
  --email user@example.com \
  --name "User Name" \
  --password-stdin \
  --org your-org-slug \
  --project project-slug \
  --role manager

This creates the user account and grants them a membership in the specified organization and project with the role you specify. The user can then sign in to the Nexus console with their email and the password you set.

Important security note: When creating user accounts, passwords must never be passed as command-line arguments (they would be visible in shell history). Always use --password-stdin to read the password from standard input, or --password-env to read from an environment variable.

For detailed CLI instructions, see the Installation Guide.

Security Considerations for Team Management

Password Security: When creating accounts via CLI, the initial password you set should be treated as temporary. Nexus does not currently enforce password changes on first login, so you must implement your own process to ensure users change their initial passwords.

Recommended approaches:

• Send the temporary password through a secure channel (encrypted email, password manager, or secure messaging system) with explicit instructions to change it immediately
• For high-security environments, consider using a one-time secure link service (like OneTimeSecret.com) to share the initial password
• Maintain a checklist of newly created accounts and follow up to verify password changes occurred
• Schedule password rotation reminders (e.g., every 90 days) in your team calendar

If your organization uses SSO (see Single Sign-On below), password management is handled through your existing identity provider, eliminating these concerns entirely.

Principle of Least Privilege: Always assign the minimum role necessary for someone to do their job. Start with the User role by default and only promote to Auditor or Manager when specifically needed. It’s easier to grant additional permissions later than to revoke excessive access after a security incident. Remember that Manager role has full administrative control, so assign it sparingly.

Regular Access Reviews: Periodically audit who has access to your organization and projects. Remove team members who have changed roles, left the company, or no longer need access. Inactive accounts are security risks. Even if the person is not actively using Nexus, their credentials could be compromised. Schedule quarterly reviews to verify that all active users still require their current level of access.

Separation of Duties: Avoid giving one person control over multiple critical functions. For example, the person who creates API keys should not be the same person who approves budget increases or reviews audit logs for compliance. This separation reduces the risk of insider threats and mistakes.

Invitation Settings

Your platform administrator controls who can create accounts in Nexus by configuring registration settings at the deployment level. These settings determine whether new users can sign up freely, need an invitation, or require administrator approval.

Open registration allows anyone with access to your Nexus URL to create an account. This is useful for small teams or development environments where you want frictionless onboarding, but it may not be appropriate for production environments or organizations with strict access controls. When open registration is enabled, anyone can visit the sign-up page and create their own account, which automatically provisions a personal workspace for them.

Invite-only registration requires users to have an invitation token before they can sign up. When you send an invitation through the console or CLI, the recipient receives an email with a unique token (starting with nxi_) and a link to the sign-up page. They must use this token to complete registration. The invitation is tied to the specific email address you invited, so the token only works for that recipient. This mode balances security with convenience. Authorized users can self-serve their account creation, but you control who receives invitations.

Closed registration completely disables the sign-up page. Only platform administrators can create accounts using the CLI or console. This is the most restrictive mode and is appropriate for high-security environments where every account must be explicitly approved and provisioned by an administrator. New users cannot create their own accounts even if they have an invitation token.

Your organization’s registration mode depends on your security requirements and onboarding process. If you are unsure which mode your deployment uses, ask your platform administrator or attempt to visit the sign-up page. The mode will be apparent based on whether you can create an account, need an invitation token, or see a message that registration is disabled.

Single Sign-On (SSO)

If your organization uses OIDC/SSO (Google Workspace, Microsoft Entra ID, or another identity provider), team members can sign in with their work credentials instead of creating a separate Nexus password. Your platform administrator configures SSO at the deployment level. For details on setting up SSO, see the Platform Administration guide.

Why it matters

Invitation-based access ensures that only authorized team members can join your organization. SSO integration reduces password fatigue and centralizes identity management.

Managing Roles and Permissions

Once team members are part of your organization, you can change their roles or adjust which projects they have access to.

Changing Roles

To change a user’s role, you need to create a new membership with the updated role. Currently, this requires:

1. Disabling the user’s current membership (see Removing or Suspending Users)
2. Creating a new membership with the updated role using the nexus auth users create command with the new role

The change takes effect immediately. If you promote someone from User to Auditor, they gain access to audit logs including all historical data. If you demote someone from Manager to User, they lose administrative permissions and can no longer view any audit logs. Role changes affect all projects where the user has that membership, so consider whether you need to adjust their access at the organization level or create separate project-specific memberships with different roles. When making role changes, notify the affected user so they understand their new permissions and responsibilities. Document the reason for the change in your internal records for future reference during access reviews or audits.

For detailed CLI instructions, see the Installation Guide.

Project-Level Access

Team members can have different roles in different projects. For example, someone might be a Manager in the Engineering organization but only a User in the Marketing organization. This separation ensures that team members have full control over their own projects without interfering with others.

When you create a new project, existing organization members do not automatically gain access to it. You must explicitly grant access by adding them to the project. This isolation prevents accidental data exposure and ensures that projects remain independent.

Why it matters

Flexible role assignment lets you grant someone elevated permissions in their area of responsibility while limiting their access elsewhere. This reduces the risk of accidental changes or data leaks.

Controlling Project Access

Beyond roles, you control access through API keys, classification ceilings, and budget limits. These controls ensure that projects can only access the data and resources they are authorized to use.

API Key Scoping

Every API key in Nexus is scoped to a specific project. This means a key created for your customer support chatbot project cannot be used to make requests on behalf of your internal analytics project. If a key is compromised, the attacker can only access data and make requests within that one project. They cannot reach other projects even if they are in the same organization.

Team members with the User or Manager role can create API keys for the projects they have access to. Auditors cannot create API keys because their role is read-only. When creating a key, you give it a descriptive name (like “Production Key” or “Development Test Key”) to track which application is using it. The key starts with nxs_ and is shown only once at creation. After that, only the key’s prefix is visible for identification.

Security practice: Treat API keys like passwords. Never commit them to version control, share them in chat or email, or log them in application logs. Rotate keys periodically (every 90 days is a common baseline) and immediately revoke any key that might have been exposed.

For detailed instructions on creating and managing API keys, see Getting Started: Creating an API Key.

Classification Ceilings

Classification ceilings control the highest sensitivity level a project can handle. For example, if your customer support chatbot project has a classification ceiling of confidential, any attempt to send a request labeled restricted will be rejected before it reaches the AI provider.

This enforcement prevents projects from accidentally processing data they are not approved to handle. You set classification ceilings when you create a project or update its settings. Classification ceilings can only get stricter as you move down the hierarchy. A project cannot have a higher ceiling than its parent organization, and an organization cannot have a higher ceiling than its workspace.

For more details on how classification works, see Using Nexus: Classifying Your Data.

Budget Limits and Rate Limits

Managers can set spending limits at the workspace, organization, or project level. These caps prevent runaway costs by blocking requests once the monthly budget is exhausted. Rate limits control how many requests per second or per minute a project can make, ensuring fair resource allocation and preventing one application from monopolizing the system.

When a project hits a budget or rate limit, Nexus rejects new requests with a clear error message explaining what happened and when the limit will reset. This gives team members visibility into why their requests are failing and whom to contact to adjust the limits.

Why it matters

Project-scoped API keys, classification ceilings, and budget limits create multiple layers of defense. If one control fails or is bypassed, the others still protect your organization’s data and spending.

Removing or Suspending Users

When someone leaves your team or no longer needs access to Nexus, you should immediately revoke their access to prevent unauthorized use. Offboarding is a critical security control that protects your organization from data breaches, unauthorized spending, and compliance violations. Every minute that passes between when someone leaves and when you disable their access creates risk. Former employees retain knowledge of your systems, projects, and data classifications, making compromised credentials particularly dangerous. Treat offboarding with the same urgency you would treat a security incident.

Suspending a User

Suspending (also called disabling) a user blocks their login without deleting their account. This is useful when someone is temporarily leaving (like a sabbatical) or when you want to preserve their audit trail while removing their active access.

To suspend a user, use the Nexus CLI:

# Suspend a user (blocks login)
nexus auth users disable user@example.com

# Re-enable a suspended user
nexus auth users enable user@example.com

Note: The CLI also accepts nexus auth users rm as an alias for disable, but this command only disables the user account. It does not delete the user record.

When you suspend a user, they can no longer sign in to the Nexus console or make API requests. Any API keys they created continue to work until you explicitly revoke them (see below). Disabled users still appear in audit logs and usage reports, preserving the historical record of their activity. Nexus does not support deleting user accounts. Users can only be disabled. This ensures audit logs remain immutable and tamper-evident for compliance purposes.

Revoking API Keys

Even if you suspend a user’s account, their API keys remain active unless you revoke them. This is important: suspending a user does not automatically revoke their API keys. You must revoke keys separately to fully remove access.

To revoke API keys:

# List API keys for a project
nexus credentials api-keys list --org your-org --project your-project

# Revoke a specific key
nexus credentials api-keys rm ak_...

Revoked keys stop working immediately. Any requests using that key will fail with a 401 Unauthorized error. Revoked keys are not deleted. They remain in the system for audit purposes but can never be reactivated.

Security warning: If you suspect a key has been compromised (leaked in logs, committed to a public repository, or accessed by an unauthorized person), revoke it immediately. Do not wait until the next scheduled access review. Compromised keys can be used to make unauthorized AI requests, potentially exposing sensitive data or incurring unexpected costs.

Removing Projects or Organizations

If you need to remove an entire project or organization (for example, after a project is completed or an organization is dissolved), you can soft-delete them using the CLI:

# Remove a project
nexus projects rm your-org/your-project

# Remove an organization (and all its projects)
nexus orgs rm your-org --cascade

Soft-deleted projects and organizations are hidden from lists but remain in the database for audit and compliance purposes. Their data is still accessible to platform administrators if needed for investigations or legal requirements.

Best Practices for Offboarding

When someone leaves your team:

1. Suspend their user account immediately to block console access
2. Revoke all API keys they created or had access to
3. Review audit logs for their recent activity to ensure nothing suspicious occurred
4. Update team documentation to reflect the change in ownership for any projects they managed
5. Transfer ownership of any critical resources (like provider keys or budgets) to an active manager
6. Notify your security team if the person had Manager or Auditor role, especially if they had access to classified data or sensitive provider credentials

Timing matters: Complete steps 1 and 2 (suspend account and revoke keys) on the person’s last day, or immediately upon notification of departure if it’s sudden. Do not delay. Every hour an inactive account remains active is a potential security exposure. If the person is being terminated for cause or under contentious circumstances, disable access before informing them of the decision.

This multi-step process ensures complete removal of access while preserving the audit trail and preventing gaps in team coverage.

Why it matters

Incomplete offboarding leaves doors open for unauthorized access. A suspended user account with active API keys is still a security risk. Revoking all access points prevents former team members from making requests or viewing sensitive data.

---

Next Steps

Now that you understand team and access management, you might want to explore:

Reporting & Audit

View audit logs, track compliance, and generate usage reports for your team.

Explore reporting →

Platform Administration

Configure deployment-wide settings like SSO, registration modes, and infrastructure.

Platform admin →

Using Nexus

Learn about classification, sessions, model selection, and day-to-day usage.

Using Nexus →