NGS Cross-Account Sharing Guide


NGS enables account owners to share services and message streams with other accounts. Enabling a service or stream for sharing is called a namespace export.

All services and streams of an account are isolated from (and invisible to) other accounts unless mutually shared (an export/import pair).

Likewise, NGS enables an account owner to selectively uptake an exported service or stream. Uptaking a service or stream into your own account is called a namespace import.

Relationship to subject namespace

Export and import shares, or grants, are scoped by message subject (with or without wildcard). Fundamentally, a subject import means that the exported subject is made visible (or addressable) as part of the importer's subject namespace. The importer may map the exported subject -- the remote subject -- to an alternative local subject in its own namespace to avoid name collisions across two independent account namespaces.

NGS maps subjects between accounts at message time and enforces entitlements.

Service and stream grants

Exports and imports have two types, service and stream. These types map directly to the two interaction styles in the underlying NATS protocol.


Request-reply exchange between requesting client and replying client (or service responder). The request subject is exported by the service responder's account (forming a service address). An importer may only publish messages to this subject (requests). The service responder is dynamically entitled to publish a cross-account response to the REPLY subject if passed in the request.

In a service exchange there need not be a reply message, i.e. a 1-way service invocation. Likewise, there may be multiple reply messages for a single request, forming a response stream.


Publish-subscribe exchange between publishing client and subscribing client on the publishing account's exported subject. An importer may only subscribe to the exported subject.

Private and public exports

An export may be made available for import by any account in NGS; this is known as a public export.

Alternatively, an account owner may make a private export. A private export may be imported by another account only if that account is in possession of a digitally-signed activation token from the exporter entitling them to do so. An activation token specifies the allowed import claims that may be applied in the target account.

Activation tokens are minted by the exporting account owner as necessary to permit each target account. Tokens are provided to the importing account owner out-of-band of NGS.

Both public and private exports may be selectively revoked from a specific importing account through a revocations list. Removing an account export grant immediately revokes visibility and access for all existing imports.

Guide Pre-requisites

The guide assumes three configured NGS accounts referred to in the guide as ACCTA, ACCTB, and ACCTC. To execute privileged administration steps as an account, NGS account setup must be complete and the user's administrative environment prepared with NGS private account credentials.

The following fictional NGS account names and public NKEYs are used in this guide:

NameAccount Public Key (NKEY)

The examples assume that a local NATS CLI context is available for each account of the same name.

See the Synadia site for more information on how to sign up for Synadia's service and the NATS documentation site for information about using nsc to manage your NATS account.

Cross-Account Share Scenarios

Basic Shares

The following guides illustrate account owner steps to cross-account share a single subject such as a business API or non-durable event message channel (i.e. At-Most-Once delivery):

JetStream Consumption Shares

These guides illustrate account owner steps to cross-account share a durable message stream that leverages JetStream technology providing At-Least-Once delivery capability to consuming applications.

Sharing JetStream Consumers cross-account requires multiple account exports. JetStream offers two architectural options for stream message delivery which is illustrated in the following guides.

Note: JetStream always streams messages from server to client, but there are two options for message delivery and flow-control architecture. Consuming JetStream as a service (Pull JS Consumer) is recommended as the default choice.

Both guides illustrate a third optional export that provides a remote account application the additional entitlement to obtain JS Consumer information (e.g. pending unprocessed messages, configuration settings, etc.) via API request.

Note: Granting another account permission to publish to your JetStream is a "basic" share scenario. Export a JetStream-ingested subject as a service to allow the remote account to publish on the subject and (optionally) receive an acknowledgement reply from JetStream (At-Least-Once publishing).

Use of JetStream Prefix

When JetStream is shared between accounts, it is assumed that each account is JetStream enabled. A JetStream-enabled account has JetStream APIs (subjects starting with $JS) present in its account namespace.

To disambiguate API calls in a cross-account scenario, JetStream APIs imported into an account from another account must be mapped to a local subject with a subject prefix different from $JS. This alternative local subject prefix is called the JS Prefix and must be set accordingly in the importing account's client application code.

The JetStream cross-account guides show usage of JS prefix.

Note: JS Prefix is a special case of general capability in subject export/import to map an alternative subject name in the importing account to avoid namespace collision.

Day 1