Skip to main content
The wit token command lets you create and manage Personal Access Tokens (PATs) for authenticating with the wit platform API and CLI.

​
Overview

wit token <command> [options]
Personal Access Tokens are used to:
  • Authenticate CLI commands with the wit server
  • Access the wit API programmatically
  • Automate tasks in CI/CD pipelines
  • Grant limited access to third-party tools

​
Commands

​
create

Create a new personal access token. 
wit token create <name> [options]

​
Options

OptionDescription
--expires, -e <days>Token expires in N days (default: never)
--scopes, -s <scopes>Comma-separated scopes (default: repo:read,repo:write)

​
Examples

# Create a basic token
wit token create "My Token"

# Create a token that expires in 30 days
wit token create "CI Token" --expires 30

# Create a token with specific scopes
wit token create "Read Only" --scopes repo:read

# Create a token with multiple scopes
wit token create "Full Access" --scopes repo:read,repo:write,repo:admin

# Create a deploy key with limited access
wit token create "Deploy Key" -e 90 -s repo:read

​
Example Output

Created personal access token

Token:

  wit_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0

Make sure to copy your token now.
You will not be able to see it again!

Name:    CI Token
Scopes:  repo:read, repo:write
Expires: 2024-04-15

Use this token in the Authorization header:
  Authorization: Bearer wit_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0
Save your token immediately after creation. For security reasons, the full token is only shown once and cannot be retrieved later.

​
list

List all your personal access tokens. 
wit token list
wit token ls

​
Example Output

Personal Access Tokens (3)

wit_a1b2...  CI Token
  ID: abc12345  Scopes: repo:read, repo:write
  Last used: 2 hours ago  •  Expires: Apr 15, 2024

wit_c3d4...  [EXPIRED] Old Deploy Key
  ID: def67890  Scopes: repo:read
  Never used  •  Expired: Mar 1, 2024

wit_e5f6...  Local Development
  ID: ghi11223  Scopes: repo:read, repo:write, user:read
  Last used: 5 minutes ago  •  Expires: Never

​
revoke

Revoke (delete) a personal access token. 
wit token revoke <id>
wit token delete <id>
wit token rm <id>

​
Arguments

ArgumentDescription
idToken ID or prefix (from wit token list)

​
Examples

# Revoke by full ID
wit token revoke abc12345-6789-...

# Revoke by ID prefix
wit token revoke abc12

# Revoke by token prefix
wit token revoke wit_a1b2

​
Example Output

Revoked token: CI Token
  wit_a1b2...

​
scopes

List all available token scopes and their descriptions. 
wit token scopes

​
Example Output

Available Token Scopes

repo:read
  Clone and pull repositories

repo:write
  Push to repositories

repo:admin
  Manage repository settings, collaborators, and deletion

user:read
  Read your profile information

user:write
  Update your profile

​
Token Scopes

Scopes limit what a token can do. Always use the minimum scopes needed.
ScopeDescriptionUse Cases
repo:readClone, pull, fetch repositoriesCI builds, read-only tools
repo:writePush to repositoriesCI deployments, automation
repo:adminManage settings, collaborators, delete reposAdmin scripts, setup automation
user:readRead profile informationIntegrations, analytics
user:writeUpdate profileProfile automation

​
Scope Combinations

Common scope combinations for different use cases: 
# CI/CD Pipeline (pull and push)
wit token create "CI Pipeline" -s repo:read,repo:write

# Read-only monitoring
wit token create "Monitor" -s repo:read,user:read

# Full administrative access
wit token create "Admin Tool" -s repo:read,repo:write,repo:admin,user:read,user:write

# Minimal deployment key
wit token create "Deploy" -e 7 -s repo:read

​
Using Tokens

​
Environment Variable

Set the WIT_TOKEN environment variable: 
export WIT_TOKEN=wit_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0

​
Authorization Header

Use the token in API requests: 
curl -H "Authorization: Bearer wit_a1b2c3d4..." \
  https://your-wit-server.com/api/repos

​
Git Credential Helper

Configure git to use your token: 
# In your .gitconfig or via git config
git config --global credential.helper store

# Then use your token as the password when prompted
# Username: your-email@example.com
# Password: wit_a1b2c3d4...

​
Security Best Practices

Set expiration dates for tokens, especially those used in CI/CD:
wit token create "CI" --expires 30
Only grant the permissions the token actually needs:
# Bad: Full access when you only need to read
wit token create "Read" -s repo:read,repo:write,repo:admin

# Good: Only the required scope
wit token create "Read" -s repo:read
Create new tokens and revoke old ones periodically:
wit token create "New CI Token" --expires 30
wit token revoke old-token-id
Use environment variables or secret management tools instead of hardcoding tokens in code.
Regularly audit and revoke tokens that are no longer needed:
wit token list
wit token revoke unused-token-id

​
Workflow Examples

​
CI/CD Setup

# Create a CI token with 90-day expiration
wit token create "GitHub Actions" --expires 90 --scopes repo:read,repo:write

# Save the token as a GitHub secret: WIT_TOKEN

# In your workflow:
# env:
#   WIT_TOKEN: ${{ secrets.WIT_TOKEN }}

​
Automation Script

#!/bin/bash
# deploy.sh

# Token is set via environment
if [ -z "$WIT_TOKEN" ]; then
  echo "Error: WIT_TOKEN not set"
  exit 1
fi

# Use token for API calls
curl -H "Authorization: Bearer $WIT_TOKEN" \
  https://wit.example.com/api/repos/myorg/myrepo/releases

​
Token Rotation

# Create new token
wit token create "CI Token v2" -e 30 -s repo:read,repo:write

# Update your CI secrets with the new token

# List tokens to find the old one
wit token list

# Revoke the old token
wit token revoke old-token-id

​
Requirements

The token command requires:
  1. Database connection: Set DATABASE_URL environment variable
  2. User authentication: Set WIT_USER_ID environment variable
# Example setup
export DATABASE_URL=postgresql://wit:wit@localhost:5432/wit
export WIT_USER_ID=your-user-id

# Now token commands will work
wit token create "My Token"
When using wit up to start the platform, these are configured automatically. The WIT_USER_ID can be obtained from the web UI after logging in.