Authentication

Edge Connector Security

The Edge Connector must authenticate with the nara platform before it can receive and execute tool calls. Authentication establishes the connector’s identity, links it to your organization, and authorizes it to access the platform server. This page covers the available authentication modes, token lifecycle, and security best practices.

Authentication modes

The Edge Connector supports three authentication methods, each suited to different deployment scenarios.

Browser OAuth

Browser OAuth is the interactive authentication method designed for desktop mode. It opens your default browser, redirects you to the nara login page, and returns a JWT token after successful authorization.

edge-connector auth --browser

How it works:

1. The CLI contacts the platform and receives an authorization code and a browser URL.

2. The CLI opens the browser URL. You log in with your account and approve the Edge Connector’s access to your organization.

3. After approval, the CLI automatically retrieves the session token.

4. The token is validated (expiry, organization membership) and saved to the configured token path.

5. The default bundle for your organization is synced automatically.

This mode is the default when you run the Edge Connector runtime on a desktop machine. If no token is found at startup, the runtime automatically initiates the browser OAuth flow.

Deployment Credentials

Deployment credentials are designed for headless, server, and cloud deployments where no browser is available. Instead of interactive OAuth, the Edge Connector uses a DEPLOYMENT_ID and DEPLOYMENT_SECRET pair provided as environment variables.

export DEPLOYMENT_ID="dep_abc123"
export DEPLOYMENT_SECRET="sec_xyz789"

How it works:

• The runtime detects the presence of both DEPLOYMENT_ID and DEPLOYMENT_SECRET environment variables at startup.
• Instead of loading a JWT token, the runtime passes these credentials directly to the platform client during the WebSocket handshake.
• The platform server validates the credentials against the deployment record and establishes the connection.
• No token file is created or needed.

This mode is used automatically when both environment variables are set. It takes precedence over token-based authentication.

Tip

Deployment credentials are created and managed from the nara admin panel under Deployments. Each deployment has a unique ID and secret pair.

Token File

Token file authentication is useful for automated setups where you pre-provision the token before starting the runtime.

edge-connector auth --token /path/to/auth-token.json

Token file format:

The token file is a JSON file containing the JWT and a timestamp:

{
  "token": "eyJhbGciOiJSUzI1NiIs...",
  "savedAt": "2025-01-15T10:30:00.000Z"
}

You can also pass a raw JWT string directly:

edge-connector auth --token "eyJhbGciOiJSUzI1NiIs..."

The CLI resolves the input: if it is a valid file path, it reads the file and extracts the token field. If it is a raw string, it uses it directly as the JWT.

Token validation

Every token is validated before it is saved or used. The validation checks:

Check	Description
Format	The token must be a valid access token
Expiry	The token must still be valid and not expired
Organization	The token must belong to an organization your account can use with this connector

If any check fails, the CLI reports a specific error message and exits without saving.

Token storage

Tokens are stored as JSON files on the local file system. The storage location is determined by the following precedence:

1. The AUTH_TOKEN_PATH environment variable, if set.

2. The authTokenPath field in config.json.

3. The default path: ./auth-token.json (relative to the installation directory).

The token file is created with restrictive permissions (0600 — owner read/write only) and the containing directory is set to 0700 (owner only). This ensures the token is not readable by other users on the system.

Token refresh and expiry

JWT tokens have an expiration time set by the nara platform. When a token expires:

• Desktop mode: The runtime detects the expired token during validation and automatically initiates a new browser OAuth flow. If the system tray is active, it shows a “pending” status while re-authentication is in progress.
• Server mode with deployment credentials: Not applicable — deployment credentials do not expire in the same way as JWT tokens. The credentials remain valid as long as the deployment exists.
• Token file mode: You must manually replace the token file with a fresh token. The runtime will fail to connect if the token has expired.

The runtime validates the token at startup and logs a warning if the token is near expiry.

Desktop auth flow

The desktop authentication flow is a two-step process that allows a headless CLI to authenticate via a browser on the same machine.

CLI                    Platform                   Browser
 |                        |                          |
 |-- POST /start -------->|                          |
 |<-- code + url ---------|                          |
 |                        |                          |
 |-- open browser --------|------------------------->|
 |                        |<-- user logs in ---------|
 |                        |<-- user approves --------|
 |                        |                          |
 |-- GET /session/token ->|                          |
 |<-- JWT token ----------|                          |
 |                        |                          |
 |-- save token           |                          |

Environment variable overrides

Authentication-related environment variables override config file values:

Variable	Description
AUTH_TOKEN_PATH	Override the path where the token file is stored
DEPLOYMENT_ID	Deployment identifier for cloud/server mode
DEPLOYMENT_SECRET	Deployment secret for cloud/server mode
DEPLOYMENT_CREDENTIALS_PATH	Path to a file containing deployment credentials

Security best practices

• Never commit token files or deployment secrets to version control. Add auth-token.json and credential files to your .gitignore. - Use environment variables or secrets managers for production deployments instead of token files. - Rotate deployment credentials periodically from the admin panel. - The token file should only be readable by the user running the Edge Connector (chmod 600 auth-token.json). - When running in containers, inject credentials via environment variables or mounted secrets, not baked into the image.