Personal Access Tokens

Personal Access Tokens (PATs) are static API tokens tied to your NetDefense account. They let ndcli authenticate without going through the interactive browser-based login flow — making them the right tool for CI/CD pipelines, GitHub Actions, headless servers, and any automated script that runs without a human present.

What is a Personal Access Token?

A PAT is a long-lived credential you create once and store in your CI system’s secret store. Any ndcli call that needs you to be signed in can read the token from the NDCLI_TOKEN environment variable instead, within the limits under Permission model.

Tokens have a ndpat_ prefix so they are instantly recognizable in logs and config files.

Precedence

ndcli checks for a credential in this order, every time it runs:

1. NDCLI_TOKEN — if set and it validates as an ndpat_... token, it wins outright. Even if you’re also logged in interactively on the same machine (a cached session from ndcli auth login), the PAT takes precedence for that invocation.
2. Cached session — the tokens stored by ndcli auth login, in the keyring or file store.
3. Interactive login — if neither is present, ndcli prompts you to log in.

Note

The netdefense-mcp server supports NDCLI_TOKEN too, as of version 1.26.0, using the same precedence as ndcli. On earlier versions it’s CLI-only — the MCP server silently falls back to a cached ndcli auth login session. See the MCP server auth docs for version requirements, config examples, and the token-mutation restriction that applies under NDCLI_TOKEN.

When to use PATs

Scenario	Use PAT?
CI/CD pipeline (GitHub Actions, GitLab CI)	Yes
Headless server or scheduled cron job	Yes
Automated deployment script	Yes
Interactive terminal session	No — use ndcli auth login
Developer workstation	No — use ndcli auth login

The interactive login (ndcli auth login) remains the default for humans. PATs are for machines.

Token properties

Each PAT has the following attributes:

Property	Description
Name	A human-readable label you assign. Unique per account.
Scope	RW (read and write) or RO (read only).
Org	Optionally restrict the token to a single organization. Omit to allow access to all orgs your account belongs to.
Expiry	30d, 60d, 90d (default), 180d, 365d, or never.
Prefix	Always ndpat_ — shown in token lists for identification without revealing the full secret.

Permission model

The effective permission of a PAT call is the minimum of the token scope and your membership role in the organization:

Token scope	Your org role	Effective permission
RW	Superuser	RW
RW	Read-Write	RW
RW	Read-Only	RO
RO	Any	RO

A write the effective permission doesn’t allow is refused with a 403 (Write access required for organization '<org>'). Support tickets are the one exception: a read-only token can use every ticket call, opening a ticket, replying, closing or reopening it, and attaching files, because a ticket is a conversation with support, not a configuration change.

Note

Superuser-only actions — such as deleting an organization, managing member roles, or saving snippets that grant firewall administrator rights — are blocked when authenticating with a PAT, regardless of token scope. These actions always require interactive login. A PAT never carries Superuser clearance, even when it belongs to a Superuser, so a variable value saved through one doesn’t count as a Superuser’s save either.

What a token can’t do

Some operations act on your account rather than on an organization’s resources, so the table above doesn’t decide them. For these, the token’s scope does, or the call needs an interactive login:

• Interactive login only. Creating a token, revoking a token, and deleting your account are refused for every token, whatever its scope (INTERACTIVE_LOGIN_REQUIRED).
• A read-only token can’t change your account. Changing your display name, creating an organization, and accepting or declining an invitation are refused (TOKEN_READ_ONLY). Reading your account with ndcli auth me still works.
• A token restricted to one organization answers only that organization’s invitations. Accepting or declining an invitation to any other organization is refused (TOKEN_ORG_MISMATCH). Creating an organization isn’t tied to one: a read-write token can do it whatever organization it is restricted to.

Each of these refusals is a 403 with a code, and ndcli shows it:

Error: [TOKEN_READ_ONLY] This token is read-only; use a read-write token or an interactive login

Caution

PATs do not refresh. Interactive login (ndcli auth login) stores a refresh token and renews your session silently in the background. A PAT has no refresh token — when it reaches its --expiry, every request using it starts failing with an authentication error. There is no automatic renewal: you create a new token, update the secret in your CI store, and revoke the old one. Plan your rotation before expiry, not after a pipeline starts failing.

Token lifecycle

1. Create — Run ndcli auth token create with a name, scope, and optional org and expiry. This needs an interactive login, and the full token value is shown exactly once.

2. Store — Copy the token into your CI system’s secret store (e.g., GitHub Actions Secrets, GitLab CI Variables) as NDCLI_TOKEN.

3. Use — Set NDCLI_TOKEN=ndpat_... in the environment before any ndcli command. No login prompt appears.

4. List — Run ndcli auth token list at any time to see all tokens for your account, their scope, expiry, and last-used time.

5. Revoke — Run ndcli auth token revoke <name> to permanently invalidate a token. This needs an interactive login too.

# Create a token
ndcli auth token create --name "github-ci" --scope rw --expiry 90d

# Use the token
NDCLI_TOKEN=ndpat_xxx ndcli device list

# List all tokens
ndcli auth token list

# Revoke a token
ndcli auth token revoke github-ci

Managing tokens in the web UI

PATs can also be created and revoked from Settings > Personal Access Tokens in the NetDefense web UI. The list view shows the same information as ndcli auth token list.

Security best practices

Caution

The full token value is shown only once at creation time. If you lose it, revoke the token and create a new one.

Store tokens as secrets, never in code. Use your CI platform’s secret store — GitHub Actions Secrets, GitLab CI Variables, Vault, or a similar secrets manager. Never commit a token to source control.

Use org-scoped RO tokens for read-only CI jobs. If a pipeline only reads device lists or sync status, create a token with --scope ro --org <your-org>. A compromised RO token can read, and can work with support tickets, but every other write is refused, account-level ones included — see Permission model and What a token can’t do.

Set a reasonable expiration. 90 days is the default. Align expiry with your team’s rotation policy. Tokens set to never expire should be used only when rotation is enforced by another mechanism.

Rotate tokens periodically. The safe rotation sequence is: create the new token → update the secret in CI → verify the pipeline succeeds → revoke the old token. See the Automation & CI/CD guide for a script example.

Revoke immediately if a token is leaked. Run ndcli auth token revoke <name> as soon as you suspect exposure. Then audit last_used_at in ndcli auth token list to check for unauthorized use.

Limit the number of tokens. Each account may hold at most 25 active tokens. Revoke tokens that are no longer in use.

Reference

• ndcli auth token command reference — full flag documentation and output examples
• Automation & CI/CD guide — GitHub Actions, GitLab CI, and scripting examples