API Tokens

Generate workspace tokens for programmatic access, Claude Desktop integration, and CLI authentication.

Token Overview

Workspace tokens provide programmatic access to your NimbleBrain workspace:

CLI Authentication

Use tokens to authenticate the NimbleTools CLI (ntcli)

API Access

Call the NimbleTools API from scripts and applications

CI/CD Pipelines

Automate deployments in GitHub Actions, GitLab CI, etc.

Claude Desktop

Authenticate connections in Claude Desktop

Token Information

Each token includes:

Token ID: A unique identifier (e.g., abc343a5-604...)
Status: Active or Revoked
Created Date: When the token was generated
Description: Optional label to identify the token’s purpose

Security Note: API tokens provide programmatic access to this workspace. Keep them secure and rotate regularly. Tokens are only shown once upon creation.

Creating Tokens

Navigate to API Tokens

Click “API Tokens” in the sidebar under Workspace Settings

Click Create Token

Click the blue Create Token button

Configure Token

Fill in token details:

Name/Description: Optional label to identify the token’s purpose (e.g., “Claude Desktop”, “CI/CD”)

Generate & Copy

Click Create and immediately copy the token value

Important: Token values are only shown once! If you lose it, you’ll need to generate a new token.

Using Tokens

With NimbleTools CLI

Set your token as an environment variable:

# Set token for current session
export NTCLI_TOKEN=your-workspace-token

# Verify authentication
ntcli auth status

# Or use the login command
ntcli auth login --token your-workspace-token

Make it permanent by adding to your shell profile:

# Add to ~/.bashrc, ~/.zshrc, or ~/.profile
echo 'export NTCLI_TOKEN=your-workspace-token' >> ~/.zshrc
source ~/.zshrc

With Claude Desktop

Tokens are automatically included in generated Claude Desktop configurations:

{
  "mcpServers": {
    "server-name": {
      "command": "npx",
      "args": ["-y", "@nimbletools/mcp-client", "https://..."],
      "env": {
        "NTCLI_TOKEN": "your-workspace-token"
      }
    }
  }
}

With API Requests

Include tokens in API request headers:

# Using curl
curl -H "Authorization: Bearer your-workspace-token" \
     https://api.nimbletools.dev/v1/workspaces/{uuid}/servers

# Using httpie
http https://api.nimbletools.dev/v1/workspaces/{uuid}/servers \
     Authorization:"Bearer your-workspace-token"

// Using fetch in JavaScript
const response = await fetch('https://api.nimbletools.dev/v1/workspaces/{uuid}/servers', {
  headers: {
    'Authorization': 'Bearer your-workspace-token'
  }
});

# Using requests in Python
import requests

headers = {'Authorization': 'Bearer your-workspace-token'}
response = requests.get(
    'https://api.nimbletools.dev/v1/workspaces/{uuid}/servers',
    headers=headers
)

Managing Tokens

Viewing Active Tokens

See all tokens for the current workspace:

Open Token List

Navigate to Settings → API Tokens

Review Tokens

View token list showing:

Token name/description
Type (Standard, Long-Lived, Read-Only)
Created date
Expiration date
Last used date

Token values are never displayed after creation. You’ll only see token metadata.

Refreshing Tokens

Extend the expiration of Standard tokens:

Find Token

Locate the token in the token list

Click Refresh

Click the Refresh button (only available for Standard tokens)

Confirm Refresh

Confirm to extend expiration by another 30 days

Only Standard tokens can be refreshed. Long-Lived tokens must be regenerated when they expire.

Deleting Tokens

Immediately invalidate a token:

Locate Token

Find the token in the API Tokens list

Click Delete

Click the Delete Token button (trash icon)

Confirm Deletion

Confirm - the token will be immediately invalidated

Deleting a token immediately stops all services using it. Update integrations with a new token first!

Token Security

Best Practices

Never Commit Tokens to Git

Add tokens to .gitignore and use environment variables instead:

# .gitignore
.env
.env.local
*_token.txt

Use Read-Only Tokens for Monitoring

Create separate read-only tokens for dashboards and monitoring tools. This limits damage if a token is compromised.

Rotate Tokens Regularly

Rotate tokens every 90 days for production workspaces:

Generate new token
Update services to use new token
Verify services work with new token
Revoke old token

Use Different Tokens per Service

Create separate tokens for each CI/CD pipeline or service. This allows selective revocation without affecting other services.

Monitor Token Usage

Regularly check “Last Used” dates and revoke unused tokens to reduce attack surface.

Storing Tokens Securely

Development
CI/CD
Production

Use environment variables in .env files (don’t commit them):

# .env
NTCLI_TOKEN=your-token-here

CI/CD Integration

GitHub Actions

name: Deploy Connection

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Install ntcli
        run: npm install -g @nimbletools/ntcli

      - name: Deploy server
        env:
          NTCLI_TOKEN: ${{ secrets.NTCLI_TOKEN }}
        run: |
          ntcli workspace select my-workspace
          ntcli server deploy my-server

GitLab CI

deploy:
  image: node:20
  script:
    - npm install -g @nimbletools/ntcli
    - ntcli workspace select my-workspace
    - ntcli server deploy my-server
  variables:
    NTCLI_TOKEN: $NTCLI_TOKEN
  only:
    - main

CircleCI

version: 2.1

jobs:
  deploy:
    docker:
      - image: cimg/node:20.0
    steps:
      - checkout
      - run: npm install -g @nimbletools/ntcli
      - run: |
          export NTCLI_TOKEN=$NTCLI_TOKEN
          ntcli workspace select my-workspace
          ntcli server deploy my-server

workflows:
  main:
    jobs:
      - deploy:
          filters:
            branches:
              only: main

Token Expiration Handling

Automatic Refresh (CLI)

The CLI can automatically refresh Standard tokens:

# Enable auto-refresh
ntcli config set auto-refresh-token true

# The CLI will automatically refresh your token before it expires

Manual Refresh

For services that don’t auto-refresh:

Monitor Expiration

Set a calendar reminder 7 days before token expiration

Generate New Token

Create a new token in Studio

Update Services

Update environment variables or CI/CD secrets

Verify

Test that services work with new token

Revoke Old Token

Revoke the old token after verifying the new one works

Troubleshooting

Error: Invalid token

Causes:

Token expired
Token was revoked
Token is for wrong workspace

Solution:

Generate a new token in Studio
Update your environment variables
Verify you’re using the correct workspace

Error: Permission denied

Causes:

Using read-only token for write operation
Token doesn’t have required permissions

Solution:

Generate a Standard or Long-Lived token (not Read-Only)
Verify the token is for the correct workspace

Token not working in Claude Desktop

Causes:

Token not properly set in config file
Claude Desktop not restarted

Solution:

Verify NTCLI_TOKEN is in the env section
Fully quit and restart Claude Desktop

Workspace Management

Learn about workspace isolation and security

CLI Authentication

Authenticate the NimbleTools CLI

API Architecture

Understand API authentication flows

CI/CD Guide

Automate deployments with CI/CD

Getting Started

Building Automations

Connections

Workspace & Settings

Token Overview

CLI Authentication

API Access

CI/CD Pipelines

Claude Desktop

Token Information

Creating Tokens

Using Tokens

With NimbleTools CLI

With Claude Desktop

With API Requests

Managing Tokens

Viewing Active Tokens

Refreshing Tokens

Deleting Tokens

Token Security

Best Practices

Storing Tokens Securely

CI/CD Integration

GitHub Actions

GitLab CI

CircleCI

Token Expiration Handling

Automatic Refresh (CLI)

Manual Refresh

Troubleshooting

Workspace Management

CLI Authentication

API Architecture

CI/CD Guide

Getting Started

Building Automations

Connections

Workspace & Settings

​Token Overview

CLI Authentication

API Access

CI/CD Pipelines

Claude Desktop

​Token Information

​Creating Tokens

​Using Tokens

​With NimbleTools CLI

​With Claude Desktop

​With API Requests

​Managing Tokens

​Viewing Active Tokens

​Refreshing Tokens

​Deleting Tokens

​Token Security

​Best Practices

​Storing Tokens Securely

​CI/CD Integration

​GitHub Actions

​GitLab CI

​CircleCI

​Token Expiration Handling

​Automatic Refresh (CLI)

​Manual Refresh

​Troubleshooting

​Related Documentation

Workspace Management

CLI Authentication

API Architecture

CI/CD Guide

Token Overview

Token Information

Creating Tokens

Using Tokens

With NimbleTools CLI

With Claude Desktop

With API Requests

Managing Tokens

Viewing Active Tokens

Refreshing Tokens

Deleting Tokens

Token Security

Best Practices

Storing Tokens Securely

CI/CD Integration

GitHub Actions

GitLab CI

CircleCI

Token Expiration Handling

Automatic Refresh (CLI)

Manual Refresh

Troubleshooting

Related Documentation