Skip to main content

​
Overview

Revoke a specific workspace token by its JWT ID (JTI). This immediately invalidates the token and prevents further use. This command requires Clerk authentication and cannot revoke tokens using workspace token authentication.

​
Syntax

ntcli token revoke <jti> [options]

​
Arguments

​
jti
string
required
JWT ID of the token to revokeFormat: jti_* (e.g., jti_abc123def456)
Source: Use ntcli token list to find JTI values

​
Options

​
--force
boolean
Skip confirmation promptDefault: false
Use case: Automated scripts and CI/CD pipelines
​
--format
string
Output format for the revocation resultDefault: text
Options: text, json

​
Authentication Requirements

Clerk Authentication Required: Token revocation requires Clerk authentication, not workspace tokens. You must be logged in with ntcli auth login.
This design prevents workspace tokens from revoking themselves or other tokens, which could lead to security vulnerabilities.

​
Examples

​
Revoke Specific Token

# Revoke a token with confirmation
ntcli token revoke jti_abc123def456
Output: 
Token jti_abc123def456 will be permanently revoked.
This action cannot be undone.

Are you sure? (y/N): y
Token jti_abc123def456 revoked successfully.

​
Force Revoke (No Confirmation)

# Revoke token without confirmation prompt
ntcli token revoke jti_abc123def456 --force
Output: 
Token jti_abc123def456 revoked successfully.

​
JSON Output

# Get revocation result in JSON format
ntcli token revoke jti_abc123def456 --force --format json
Output: 
{
  "jti": "jti_abc123def456",
  "revoked_at": "2024-08-07T12:30:00Z",
  "status": "revoked"
}

​
Token Discovery Workflow

​
Find Token JTI

# List all tokens to find the JTI to revoke
ntcli token list
Output: 
┌─────────────────────┬─────────────────────┬─────────────────────┬─────────┐
│ JTI                 │ Created             │ Expires             │ Current │
├─────────────────────┼─────────────────────┼─────────────────────┼─────────┤
│ jti_abc123def456    │ 2024-08-07 10:30:00 │ 2025-08-07 10:30:00 │ ✓       │
│ jti_old789xyz012    │ 2024-06-01 09:15:00 │ 2025-06-01 09:15:00 │         │
└─────────────────────┴─────────────────────┴─────────────────────┴─────────┘

​
Revoke Old Token

# Revoke the old token
ntcli token revoke jti_old789xyz012 --force

​
Bulk Token Revocation

​
Revoke Multiple Tokens

#!/bin/bash
# Script to revoke multiple old tokens

# Get list of token JTIs (excluding current token)
TOKENS=$(ntcli token list --format json | jq -r '.tokens[] | select(.is_current != true) | .jti')

for token in $TOKENS; do
    echo "Revoking $token..."
    ntcli token revoke "$token" --force
done

​
Revoke Expired Tokens

# Find and revoke expired tokens
ntcli token list --show-expired --format json | \
    jq -r '.tokens[] | select(.status == "expired") | .jti' | \
    while read jti; do
        ntcli token revoke "$jti" --force
    done

​
Security Considerations

​
Impact of Revocation

Immediate Effect: Revoked tokens become invalid immediately and cannot be restored.
Current Token: If you revoke your current token, you’ll need to refresh to get a new one.

​
What Happens After Revocation

  1. API Calls Fail: Any systems using the revoked token will receive authentication errors
  2. CI/CD Impact: Automated systems using the token will fail
  3. No Recovery: Revoked tokens cannot be restored or reactivated

​
Best Practices

  • Verify JTI: Double-check the JTI before revoking to avoid mistakes
  • Update Systems: Update any systems using the token before revocation
  • Monitor Impact: Check logs for authentication failures after revocation
  • Document Changes: Keep records of token revocations for audit purposes

​
Error Handling

Error: Clerk authentication required for token revocationSolution: Log in with Clerk authentication:
ntcli auth login
ntcli token revoke jti_abc123
Error: Token with JTI 'jti_xyz' not foundSolution: Verify the JTI exists:
ntcli token list
ntcli token revoke jti_correct_value
Error: Invalid JTI formatSolution: Use the correct JTI format from token list:
ntcli token list  # Copy JTI exactly
ntcli token revoke jti_abc123def456
Error: Token is already revokedSolution: The token was previously revoked. Check token list:
ntcli token list --show-expired

​
Recovery After Revocation

​
If You Revoked Current Token

# Your current token was revoked, get a new one
ntcli token refresh

​
If You Revoked CI/CD Token

# Create new token for CI/CD system
NEW_TOKEN=$(ntcli token create --expires-in 31536000 --format json | jq -r '.token')
echo "Update your CI/CD system with this new token:"
echo $NEW_TOKEN

token list

List tokens to find JTI values

token create

Create replacement tokens

token refresh

Refresh current workspace token

auth login

Clerk authentication for revocation
⌘I