nsc token create

Create a revokable token with specific permissions and expiration.

nsc token create provides commands to manage revokable tokens that can be used for authentication in situations where federation is not available or practical. These tokens provide a flexible way to grant time-limited, scoped access to resources without using full workload federation.

Revokable tokens are useful for:

  • CI/CD pipelines that don't support OIDC federation
  • Local development and testing
  • Automated scripts and tools
  • Temporary access grants with expiration
  • Situations requiring explicit permission scoping

nsc token create generates a new revokable token that can be used for authentication. Tokens can be scoped to specific resources and actions, and can be configured with custom expiration times (up to 365 days).

Usage

nsc token create [flags]

Examples

Create a token with a name, description, and grant:

$ nsc token create \
  --name "ci-pipeline-token" \
  --description "Token for GitHub Actions CI pipeline" \
  --grant '{"resource_type":"github/runner-profile","resource_id":"*","actions":["*"]}'

Create a token with custom expiration:

$ nsc token create \
  --name "short-lived-builder-token" \
  --grant '{"resource_type":"builder","resource_id":"*","actions":["ensure","access"]}' \
  --expires_in 1h

Create a token with specific permissions:

$ nsc token create \
  --name "builder-token" \
  --grant '{"resource_type":"builder","resource_id":"*","actions":["ensure","access"]}' \
  --grant '{"resource_type":"artifact","resource_id":"*","actions":["create","resolve","list"]}'

Save token to file for automated usage:

$ nsc token create \
  --name "automation-token" \
  --grant '{"resource_type":"builder","resource_id":"*","actions":["ensure","access"]}' \
  --token_file token.json

Display only the token value:

$ nsc token create \
  --name "quick-token" \
  --grant '{"resource_type":"builder","resource_id":"*","actions":["ensure","access"]}' \
  --output token

Use the token with the nsc CLI:

Write the token to a file with --token_file, then point the NSC_TOKEN_FILE environment variable at it. The nsc CLI reads this variable on every invocation and authenticates with the token instead of your local login.

# 1. Create the token and save it to a file.
$ nsc token create \
  --name "cli-token" \
  --grant '{"resource_type":"instance","resource_id":"*","actions":["create","get","list","destroy"]}' \
  --token_file token.json
 
# 2. Use it for subsequent nsc CLI commands.
$ NSC_TOKEN_FILE="./token.json" nsc instance list

Flags

--name string

A unique name for the token within the tenant. This helps identify the token's purpose when listing or managing tokens.

--grant stringArray (can be repeated)

Grant specific permissions to the token as a JSON object. This flag can be specified multiple times to grant multiple permissions.

Format:

{"resource_type":"...","resource_id":"...","actions":["..."]}

See Permissions for the full list of available resource types and actions.

--description string (optional)

A human-readable description of the token's purpose. Use this to document why the token was created and what it's used for.

--expires_in duration (optional)

Duration until the token expires. The default is 24 hours. Maximum allowed duration is 365 days.

Available time units are: h (hours), d (days),w (weeks), and y (years).

Examples:

  • 1h - 1 hour
  • 24h - 24 hours (default)
  • 7d - 7 days
  • 1w - 1 week, same as 7d
  • 1y - 1 year (maximum), same as 365d

--output string (optional)

Output format for the created token. Options: table (default), json, token.

  • table: Display token information in a formatted table
  • json: Output full token details as JSON
  • token: Output only the token value (useful for scripts)

--user (optional)

Scope the token to the current user's workspace membership. By default, creating tokens requires the user to be a workspace admin. When --user is specified, the token is bound to the calling user's membership, allowing non-admin users to create tokens scoped to their own permissions.

--token_file string (optional)

Write the token to the specified file in JSON format. This is useful for automated workflows that need to store and reuse the token.

To authenticate the nsc CLI (or any Namespace SDK) with the saved token, set the NSC_TOKEN_FILE environment variable to the file's path:

export NSC_TOKEN_FILE="$(pwd)/token.json"
nsc instance list

The CLI reads the credential from this file on each invocation. Note that NSC_TOKEN_FILE expects a path to a token file, not a raw token value.

Last updated