Accounts and Multi-Tenancy

Overview

Accounts provide strong multi-tenancy in NATS by creating isolated subject namespaces. Each account maintains complete isolation from other accounts unless explicitly configured to share specific streams or services.

Multi-Tenancy with Accounts

From server/accounts.go:50-52, an Account represents a subject namespace definition where:

Messages published in one account cannot be seen by other accounts
Subscriptions exist within account boundaries
Sharing occurs only through explicit exports and imports
Each account has independent limits and quotas

The Global Account

From server/accounts.go:42-44, for backward compatibility with NATS < 2.0:

const globalAccountName = DEFAULT_GLOBAL_ACCOUNT

Users not explicitly assigned to an account are placed in the global account. In modern deployments, you should explicitly define accounts rather than relying on the global account.

Account Structure

From server/accounts.go:52-119, each account maintains:

Sublist (sl): Subscription matching tree
Client tracking: Maps of connected clients
Statistics: Message and byte counters for different connection types
Import/Export maps: Cross-account sharing configuration
JetStream context: Optional per-account JetStream resources
Limits: Connection, subscription, and payload limits
Permissions: Default permissions for account users

Account Isolation and Security Boundaries

Subject Space Isolation

Each account has its own subject space:

Account A:                    Account B:
  orders.created               orders.created
  users.login                  users.login  
  inventory.update             inventory.update

These are completely separate - a message published to orders.created in Account A will never reach subscribers in Account B (unless explicitly exported/imported).

Resource Isolation

From server/accounts.go:53-60, accounts track separate statistics:

stats struct {
    sync.Mutex
    stats       // Totals
    gw    stats // Gateways
    rt    stats // Routes  
    ln    stats // Leafnodes
}

Each account tracks:

Messages in/out
Bytes in/out
Slow consumers
Per-connection-type breakdowns

Connection Isolation

Clients connect to specific accounts:

User credentials determine account assignment
Each client belongs to exactly one account
Client can only publish/subscribe within their account
Cross-account access only via explicit imports/exports

System Account

The system account is a special privileged account used for monitoring and management.

System Account Role

From server/server.go:192, the server maintains a reference to the system account:

sys                 *internal
sysAcc              atomic.Pointer[Account]

The system account:

Receives server events and metrics
Provides monitoring endpoints
Handles server-to-server communication
Cannot be used for regular application messaging

System Account Configuration

accounts {
  SYS: {
    users: [
      {user: "admin", password: "admin_pass"}
    ]
  }
  APP: {
    users: [
      {user: "app", password: "app_pass"}
    ]
  }
}

system_account: "SYS"

Never use the system account for application traffic. It has special privileges and bypass certain limits.

System Account Events

The system account receives:

Connection events: $SYS.ACCOUNT.*.CONNECT
Disconnect events: $SYS.ACCOUNT.*.DISCONNECT
Server stats: $SYS.SERVER.*.STATSZ
JetStream advisories: $JS.EVENT.ADVISORY.>

Subscribe to these subjects in the system account for monitoring.

JWT-Based Authentication

NATS supports decentralized authentication using JSON Web Tokens (JWTs).

JWT Architecture

From server/accounts.go:36 and server/auth.go:33:

import (
    "github.com/nats-io/jwt/v2"
    "github.com/nats-io/nkeys"
)

JWT authentication uses:

Operator JWT: Root of trust, signs accounts
Account JWT: Defines account properties and limits
User JWT: Credentials for individual users
NKeys: Ed25519 key pairs for signing and verification

JWT Components

From server/accounts.go:64-66:

Nkey         string
Issuer       string  
claimJWT     string

Each account stores:

Nkey: Account’s public key
Issuer: Operator’s public key that signed this account
claimJWT: The full JWT claim

Signing Keys

From server/accounts.go:98-99:

signingKeys  map[string]jwt.Scope
extAuth      *jwt.ExternalAuthorization

Accounts support:

Multiple signing keys: Rotate keys without downtime
Scoped keys: Limit what each signing key can authorize
External authorization: Delegate authentication to external services

JWT Configuration

Enable JWT mode:

operator: "/path/to/operator.jwt"
resolver: {
  type: "full"
  dir: "/path/to/jwt/storage"
}

Or use URL resolver:

operator: "/path/to/operator.jwt"  
resolver: "URL(http://jwt-resolver.example.com:8080/jwt/v1/accounts/)" 

User Credentials

Users authenticate with credential files:

-----BEGIN NATS USER JWT-----
eyJ0eXAiOiJqd3QiLCJhbGciOiJlZDI1NTE5...
------END NATS USER JWT------

************************* IMPORTANT *************************
NKEY Seed printed below can be used to sign and prove identity.
    NKEYs are sensitive and should be treated as secrets.

-----BEGIN USER NKEY SEED-----
SUACCSSUZZMCJWVYW3OEQZ6NNFMWP...
------END USER NKEY SEED------

Clients load credentials:

nc, err := nats.Connect("nats://localhost:4222",
    nats.UserCredentials("/path/to/user.creds"))

Account Limits and Quotas

From server/accounts.go:126-133, accounts support limits:

type limits struct {
    mpay           int32  // Max payload size
    msubs          int32  // Max subscriptions
    mconns         int32  // Max connections  
    mleafs         int32  // Max leaf node connections
    disallowBearer bool   // Disallow bearer tokens
}

Connection Limits

Limit the number of connections per account:

accounts {
  APP: {
    users: [{user: "app", password: "pass"}]
    limits: {
      max_connections: 1000
      max_leafnodes: 10
    }
  }
}

From server/accounts.go:77-80, the server tracks:

nrclients    int32  // Number of remote clients
sysclients   int32  // Number of system clients  
nleafs       int32  // Number of leaf nodes
nrleafs      int32  // Number of remote leaf nodes

Subscription Limits

Limit subscriptions per account:

accounts {
  APP: {
    users: [{user: "app", password: "pass"}]
    limits: {
      max_subscriptions: 10000
    }
  }
}

Exceeding limits results in client errors.

Payload Size Limits

Limit maximum message size:

accounts {
  APP: {
    users: [{user: "app", password: "pass"}]
    limits: {
      max_payload: 1048576  # 1MB
    }
  }
}

From server/server.go:123, the server advertises max payload:

MaxPayload        int32    `json:"max_payload"`

JetStream Limits

From server/accounts.go:93:

jsLimits     map[string]JetStreamAccountLimits

JetStream limits per account:

accounts {
  APP: {
    jetstream: {
      max_memory: 1073741824      # 1GB
      max_file: 10737418240       # 10GB  
      max_streams: 100
      max_consumers: 1000
    }
  }
}

Exports and Imports

Accounts can selectively share streams or services.

Stream Exports

From server/accounts.go:142-150, stream imports:

type streamImport struct {
    acc     *Account
    from    string           // Remote subject
    to      string           // Local subject
    tr      *subjectTransform
    claim   *jwt.Import
    usePub  bool
    invalid bool
}

Export a stream:

accounts {
  ORDERS: {
    exports: [
      {stream: "orders.>"}
    ]
  }
  
  FULFILLMENT: {
    imports: [
      {stream: {account: "ORDERS", subject: "orders.>"}, prefix: "external.orders"}
    ]
  }
}

Messages published to orders.shipped in ORDERS appear as external.orders.shipped in FULFILLMENT.

Service Exports

Export request-reply services:

accounts {
  AUTH: {
    exports: [
      {service: "auth.validate"}
    ]
  }
  
  APP: {
    imports: [
      {service: {account: "AUTH", subject: "auth.validate"}}
    ]
  }
}

APP can send requests to auth.validate which are handled by AUTH account services.

Subject Transforms

From server/accounts.go:146-147, imports support transformations:

tr      *subjectTransform
rtr     *subjectTransform  // Reverse transform

Transform subjects during import:

imports: [
  {
    stream: {account: "SOURCE", subject: "old.>"}
    to: "new.>"  # Maps old.foo -> new.foo
  }
]

Account Management

Static Configuration

Define accounts in configuration file:

accounts {
  ACCOUNT_A: {
    users: [
      {user: "user_a", password: "pass_a"}
    ]
  }
  ACCOUNT_B: {
    users: [
      {user: "user_b", password: "pass_b"}  
    ]
  }
}

JWT-Based Management

Use JWT resolver for dynamic account management:

Create operator and signing key
Issue account JWTs signed by operator
Issue user JWTs signed by account
Configure server with operator JWT and resolver
Server fetches account JWTs from resolver as needed

This enables:

Adding accounts without server restart
Updating account limits dynamically
Revoking user credentials
Account delegation

Account Revocation

From server/accounts.go:84:

usersRevoked map[string]int64

Revoke user credentials:

nsc revocations add_user --account ACCOUNT --user-public-key NKEY

Revoked users are immediately disconnected.

Account Updates

From server/accounts.go:67:

updated      time.Time

With JWT resolver:

Server periodically checks for account updates
Updated JWTs apply to new connections immediately
Existing connections use permissions from connection time
Can force disconnect for immediate updates

Account Best Practices

Account Design

One account per tenant: Isolate customers completely
System account separation: Never mix application and monitoring
Service accounts: Dedicated accounts for shared services
Environment separation: Separate dev/staging/prod accounts

Security

Use JWT authentication: Centralized, revocable credentials
Set appropriate limits: Prevent resource exhaustion
Minimal exports: Only share what’s necessary
Audit imports: Know what external data you consume
Rotate signing keys: Regular key rotation for security

Performance

Account-level optimization: Some routes can be account-dedicated
Limit account count: Many accounts increase overhead
Monitor account metrics: Track per-account resource usage
Subject planning: Design subjects for efficient routing

Operations

Use JWT resolver: Enable dynamic account management
Monitor system account: Subscribe to server events
Set up alerts: Track limit violations
Document exports: Maintain export/import relationships
Test failover: Verify account isolation during failures

Monitoring Accounts

Account Statistics

From server monitoring endpoints:

/accountz: List all accounts and basic stats
/connz?acc=ACCOUNT: Connections for specific account
/subsz?acc=ACCOUNT: Subscriptions for specific account

System Account Monitoring

Subscribe in system account:

// Connection tracking
nc.Subscribe("$SYS.ACCOUNT.*.CONNECT", func(m *nats.Msg) {
    // Log connections
})

// Account statistics  
nc.Subscribe("$SYS.REQ.ACCOUNT.*.STATSZ", func(m *nats.Msg) {
    // Process account stats
})

JetStream Account Monitoring

For accounts with JetStream:

// Stream events
nc.Subscribe("$JS.EVENT.ADVISORY.STREAM.*", func(m *nats.Msg) {
    // Track stream operations
})

// Consumer events  
nc.Subscribe("$JS.EVENT.ADVISORY.CONSUMER.*", func(m *nats.Msg) {
    // Track consumer operations
})

Advanced Account Features

Account Trace Sampling

From server/accounts.go:113-115:

traceDest         string
traceDestSampling int

Configure message tracing per account:

Route trace messages to specific destination
Sample percentage of traced messages
Useful for debugging message flow

Account Tags

From server/accounts.go:106-107:

tags         jwt.TagList
nameTag      string

Tag accounts for organization and filtering:

{
  "tags": ["production", "tier-1", "region-us-west"]
}

External Authorization

From server/accounts.go:99:

extAuth      *jwt.ExternalAuthorization

Delegate authorization decisions to external services:

Server calls external service for auth decisions
Enables integration with existing auth systems
Supports custom authorization logic
Can use for publish/subscribe permission checks

Next Steps

Architecture Overview

Review overall NATS architecture

Clustering

Deploy accounts across clusters

Gateways

Share accounts across regions with gateways

Get Started

Deployment

Architecture

Features

Operations

Configuration

​Overview

​Multi-Tenancy with Accounts

​The Global Account

​Account Structure

​Account Isolation and Security Boundaries

​Subject Space Isolation

​Resource Isolation

​Connection Isolation

​System Account

​System Account Role

​System Account Configuration

​System Account Events

​JWT-Based Authentication

​JWT Architecture

​JWT Components

​Signing Keys

​JWT Configuration

​User Credentials

​Account Limits and Quotas

​Connection Limits

​Subscription Limits

​Payload Size Limits

​JetStream Limits

​Exports and Imports

​Stream Exports

​Service Exports

​Subject Transforms

​Account Management

​Static Configuration

​JWT-Based Management

​Account Revocation

​Account Updates

​Account Best Practices

​Account Design

​Security

​Performance

​Operations

​Monitoring Accounts

​Account Statistics

​System Account Monitoring

​JetStream Account Monitoring

​Advanced Account Features

​Account Trace Sampling

​Account Tags

​External Authorization

​Next Steps

Architecture Overview

Clustering

Gateways

Build docs developers (and LLMs) love

Overview

Multi-Tenancy with Accounts

The Global Account

Account Structure

Account Isolation and Security Boundaries

Subject Space Isolation

Resource Isolation

Connection Isolation

System Account

System Account Role

System Account Configuration

System Account Events

JWT-Based Authentication

JWT Architecture

JWT Components

Signing Keys

JWT Configuration

User Credentials

Account Limits and Quotas

Connection Limits

Subscription Limits

Payload Size Limits

JetStream Limits

Exports and Imports

Stream Exports

Service Exports

Subject Transforms

Account Management

Static Configuration

JWT-Based Management

Account Revocation

Account Updates

Account Best Practices

Account Design

Security

Performance

Operations

Monitoring Accounts

Account Statistics

System Account Monitoring

JetStream Account Monitoring

Advanced Account Features

Account Trace Sampling

Account Tags

External Authorization

Next Steps