Skip to main content
Personal Access Tokens (PATs) provide a secure way to authenticate with the wit platform API from scripts, CI/CD pipelines, and other automated workflows.

​
Overview

PATs are an alternative to OAuth for:
  • CI/CD pipelines
  • Automated scripts
  • API integrations
  • Command-line tools
Each token has:
  • A unique identifier
  • Scoped permissions
  • Optional expiration date
  • Audit trail of usage

​
Quick Start

# Create a token
wit token create my-ci-token

# List your tokens
wit token list

# Revoke a token
wit token revoke <token-id>

​
Creating Tokens

​
Basic Token

wit token create my-token
Output: 
Token created successfully

Name:    my-token
ID:      550e8400-e29b-41d4-a716-446655440000
Token:   wit_abc123...xyz789
Scopes:  repo:read, repo:write
Expires: Never

IMPORTANT: Copy this token now. You won't be able to see it again!

To use this token:
  export WIT_TOKEN=wit_abc123...xyz789

​
Token with Expiration

# Expires in 30 days
wit token create deploy-token --expires 30

# Expires in 90 days
wit token create ci-token --expires 90

​
Token with Limited Scopes

# Read-only access
wit token create readonly-token --scopes repo:read

# Multiple scopes
wit token create admin-token --scopes repo:read,repo:write,repo:admin

​
Token Scopes

ScopeDescription
repo:readRead repository data (clone, fetch, view)
repo:writeWrite repository data (push, create branches)
repo:adminAdmin operations (delete, settings)
user:readRead user profile information
user:writeUpdate user profile

​
View Available Scopes

wit token scopes

Available Token Scopes

Repository:
  repo:read    Read repository data (clone, fetch)
  repo:write   Write to repositories (push)
  repo:admin   Admin operations (delete, settings)

User:
  user:read    Read user profile
  user:write   Update user profile

​
Managing Tokens

​
List Tokens

wit token list

Your Personal Access Tokens

ID                                     Name          Scopes              Last Used      Expires
550e8400-e29b-41d4-a716-446655440000   ci-token      repo:read,write     2 hours ago    in 30 days
660f9500-f30c-52e5-b827-557766550111   deploy-token  repo:read           5 days ago     Never

​
Revoke Token

wit token revoke 550e8400-e29b-41d4-a716-446655440000

Token revoked successfully

​
Using Tokens

​
Environment Variable

export WIT_TOKEN=wit_abc123...xyz789

# Now all wit commands use this token
wit push origin main

​
In CI/CD

​
GitHub Actions

name: Deploy

on: [push]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Push to wit
        env:
          WIT_TOKEN: ${{ secrets.WIT_TOKEN }}
        run: |
          wit remote add production https://wit.example.com/repo
          wit push production main

​
GitLab CI

deploy:
  script:
    - export WIT_TOKEN=$WIT_TOKEN
    - wit push production main
  variables:
    WIT_TOKEN: $WIT_TOKEN

​
Jenkins

pipeline {
    environment {
        WIT_TOKEN = credentials('wit-token')
    }
    stages {
        stage('Deploy') {
            steps {
                sh 'wit push production main'
            }
        }
    }
}

​
In Scripts

#!/bin/bash

# Use token for API operations
WIT_TOKEN="wit_abc123..." wit push origin main

# Or export for multiple commands
export WIT_TOKEN="wit_abc123..."
wit fetch origin
wit push origin main

​
API Usage

# Using curl with token
curl -H "Authorization: Bearer wit_abc123..." \
  https://api.wit.example.com/v1/repos

// Using the wit API client
import { getApiClient } from 'wit/api';

const api = getApiClient({
  token: process.env.WIT_TOKEN
});

const repos = await api.repos.list();

​
Security Best Practices

​
1. Use Minimal Scopes

Only request the permissions you need: 
# Bad: Full access for read-only operation
wit token create reader --scopes repo:read,repo:write,repo:admin

# Good: Minimal scope
wit token create reader --scopes repo:read

​
2. Set Expiration

For CI/CD tokens, set reasonable expiration: 
# Token expires in 90 days
wit token create ci-token --expires 90

​
3. Use Secrets Management

Never hardcode tokens: 
# Bad
WIT_TOKEN="wit_abc123..." in code

# Good
WIT_TOKEN from environment/secrets manager

​
4. Rotate Regularly

Create new tokens and revoke old ones periodically: 
# Create new token
wit token create ci-token-v2 --expires 90

# Update CI/CD secrets

# Revoke old token
wit token revoke <old-token-id>

​
5. Audit Usage

Monitor token usage: 
wit token list
Check “Last Used” to identify inactive tokens.

​
Token Format

wit tokens follow this format: 
wit_<prefix>_<random>
  • wit_ - Identifies as a wit token
  • <prefix> - First 8 characters (visible in UI)
  • <random> - Cryptographically secure random string
Tokens are hashed before storage - the full token is only shown once at creation.

​
Comparison with Other Auth Methods

MethodBest ForExpirationRevocable
Personal Access TokenCI/CD, scriptsConfigurableYes
OAuth (GitHub)Interactive loginSessionVia GitHub
SSH KeysGit operationsNeverYes

​
API Reference

​
Create Token

POST /api/tokens
Authorization: Bearer <session-token>
Content-Type: application/json

{
  "name": "my-token",
  "scopes": ["repo:read", "repo:write"],
  "expiresInDays": 30
}

​
List Tokens

GET /api/tokens
Authorization: Bearer <session-token>

​
Revoke Token

DELETE /api/tokens/:id
Authorization: Bearer <session-token>

​
Troubleshooting

Check that:
  1. Token is set correctly: echo $WIT_TOKEN
  2. Token hasn’t expired: wit token list
  3. Token has required scopes for the operation
Tokens cannot be retrieved after creation. You must:
  1. Revoke the old token: wit token revoke <id>
  2. Create a new one: wit token create <name>
The token may lack required scopes:
# Check token scopes
wit token list

# Create new token with correct scopes
wit token create new-token --scopes repo:read,repo:write