Skip to main content

​
Overview

Refresh your current workspace token with a new token that has updated expiration. This command automatically revokes the old token and stores the new one locally, ensuring seamless token rotation.

​
Syntax

ntcli token refresh [options]

​
Options

​
--expires-in
number
Token expiration time in secondsDefault: 31536000 (1 year)
Example: 86400 (24 hours)
​
--format
string
Output format for the refresh resultDefault: text
Options: text, json

​
Token Refresh Behavior

​
Automatic Token Revocation

When you refresh a token, the old token is automatically revoked and cannot be used again. This improves security by ensuring only one active token per refresh cycle.

​
Default Expiration

Tokens have a 1-year default expiration. This follows security best practices while providing reasonable token lifetime for most use cases.

​
Examples

​
Standard Refresh

# Refresh with default 1-year expiration
ntcli token refresh
Output: 
Token refreshed successfully.
Old token (jti_old123) has been revoked.
New token expires: 2025-08-07T12:00:00Z
New token JTI: jti_new456

​
Custom Expiration

# Refresh with 6-month expiration
ntcli token refresh --expires-in 15552000

​
Short-Lived Token

# Refresh with 24-hour expiration
ntcli token refresh --expires-in 86400

​
Non-Expiring Token

# Create non-expiring token (use with caution)
ntcli token refresh

​
JSON Output

# Get refresh result in JSON format
ntcli token refresh --format json
Output: 
{
  "new_token": {
    "jti": "jti_new456",
    "expires_at": "2025-08-07T12:00:00Z"
  },
  "old_token": {
    "jti": "jti_old123", 
    "revoked_at": "2024-08-07T12:00:00Z"
  },
  "message": "Token refreshed successfully"
}

​
Token Lifecycle

​
What Happens During Refresh

  1. Generate New Token: Creates a new token with specified expiration
  2. Store Locally: Updates local configuration with the new token
  3. Revoke Old Token: Automatically revokes the previous token
  4. Confirm Success: Displays new token information

​
Impact on Running Systems

CI/CD Systems: If you’ve shared your workspace token with CI/CD systems, they will lose access when you refresh. Use ntcli token create for dedicated CI/CD tokens instead.
Local Development: Your local ntcli commands will continue working seamlessly with the new token.

​
Best Practices

​
Regular Token Rotation

# Set up monthly token rotation
# Add to crontab or scheduled task
0 0 1 * * ntcli token refresh --expires-in 2592000  # 30 days

​
Separate Tokens for Different Purposes

# Use refresh for interactive development
ntcli token refresh

# Use create for CI/CD and automation
ntcli token create --expires-in 7776000  # 90 days for CI/CD

​
Monitor Token Expiration

# Check current token expiration
ntcli token show

​
Security Considerations

​
Automatic Revocation Benefits

  • Reduced Attack Surface: Old tokens cannot be used if compromised
  • Single Active Token: Prevents confusion about which token is current
  • Audit Trail: Clear record of token rotation events

​
Token Sharing Guidelines

  • Never Share Refreshable Tokens: Use ntcli token create for shared tokens
  • Use Dedicated CI/CD Tokens: Create separate tokens for automated systems
  • Regular Rotation: Refresh tokens regularly, especially after security incidents

​
Error Handling

Error: Authentication required. Try running ntcli token refreshSolution: This indicates you need a valid Clerk authentication session:
ntcli auth login
ntcli token refresh
Error: No workspace selectedSolution: Select a workspace first:
ntcli workspace switch my-workspace
ntcli token refresh
Error: No current token to refreshSolution: Create a new token first:
ntcli token create
# Token is automatically stored locally
Error: Invalid expiration timeSolution: Use a valid expiration in seconds:
ntcli token refresh --expires-in 86400  # 24 hours

token create

Create additional workspace tokens

token list

List all workspace tokens

token show

Show current token information

token revoke

Revoke specific tokens
⌘I