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. Every call to ndcli that would normally require an interactive login can instead read the token from the NDCLI_TOKEN environment variable.

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

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

Note

Superuser-only actions — such as deleting an organization or managing member roles — are blocked when authenticating with a PAT, regardless of token scope. These actions always require interactive login.

Token lifecycle

1. Create — Run ndcli auth token create with a name, scope, and optional org and expiry. 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.

# 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 cannot modify anything.

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