API Tokens

API tokens enable programmatic access to varsafe for CI/CD pipelines, automation scripts, and service accounts.

Overview

API tokens provide programmatic access without requiring an interactive login:

Feature	User Session	API Token
Authentication	Browser-based login	Token in environment
Expiration	30 days (rolling)	Never (until revoked)
Audit trail	Shows user email	Shows "Service Account"
Best for	Interactive CLI use	Programmatic access

Use Cases

• CI/CD pipelines — Inject secrets during build, test, and deploy stages
• Automation scripts — Cron jobs, scheduled tasks, infrastructure tooling
• Server-side applications — Backend services that fetch secrets at startup
• Development tooling — Custom scripts, internal CLIs, IDE integrations
• Docker builds — Pass secrets during container image builds
• Infrastructure as Code — Terraform, Pulumi, or Ansible workflows needing credentials

Token Limits

Each plan has a maximum number of active API tokens per team:

Plan	API Tokens
Developer (free)	5
Team	50

When you reach the limit, you'll need to revoke unused tokens or upgrade your plan to create more.

Creating API Tokens

Via Dashboard

1. Go to your team settings
2. Navigate to API Tokens
3. Click Create token
4. Enter a descriptive name (e.g., "GitHub Actions - Production Deploy")
5. Click Create
6. Copy the token immediately

DANGER

The token is only shown once. If you lose it, you'll need to create a new one.

Token Format

API tokens follow this format:

vs_at_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

The vs_at_ prefix identifies it as a varsafe API token.

Using API Tokens

Environment Variable

Set the VARSAFE_API_TOKEN environment variable (or VARSAFE_TOKEN as an alias):

export VARSAFE_API_TOKEN=vs_at_your_token_here
varsafe run -p my-project -e production -- ./deploy.sh

When VARSAFE_API_TOKEN is set, the CLI uses it instead of your user session.

CI/CD Integration

GitHub Actions

name: Deploy

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install varsafe CLI
        run: curl -fsSL https://varsafe.dev/install.sh | sh

      - name: Deploy with secrets
        run: varsafe run -p my-api -e production -- ./deploy.sh
        env:
          VARSAFE_API_TOKEN: ${{ secrets.VARSAFE_API_TOKEN }}

GitLab CI

deploy:
  stage: deploy
  script:
    - curl -fsSL https://varsafe.dev/install.sh | sh
    - varsafe run -p my-api -e production -- ./deploy.sh
  variables:
    VARSAFE_API_TOKEN: $VARSAFE_API_TOKEN

CircleCI

jobs:
  deploy:
    docker:
      - image: cimg/node:18.0
    steps:
      - checkout
      - run:
          name: Install varsafe CLI
          command: curl -fsSL https://varsafe.dev/install.sh | sh
      - run:
          name: Deploy with secrets
          command: varsafe run -p my-api -e production -- ./deploy.sh
          environment:
            VARSAFE_API_TOKEN: ${VARSAFE_API_TOKEN}

Jenkins

pipeline {
    agent any
    environment {
        VARSAFE_API_TOKEN = credentials('varsafe-api-token')
    }
    stages {
        stage('Deploy') {
            steps {
                sh 'curl -fsSL https://varsafe.dev/install.sh | sh'
                sh 'varsafe run -p my-api -e production -- ./deploy.sh'
            }
        }
    }
}

Direct API Usage

You can also use tokens directly with the API:

curl -X GET "https://api.varsafe.dev/secrets/with-values?projectId=xxx&environment=production" \
  -H "Authorization: Bearer vs_at_your_token_here"

Token Security

Best Practices

TIP

1. One token per purpose — Create separate tokens for different pipelines
2. Descriptive names — Name tokens clearly (e.g., "GitHub Actions - Staging")
3. Regular rotation — Rotate tokens periodically (every 90 days recommended)
4. Immediate revocation — Revoke tokens when no longer needed
5. Secure storage — Store tokens in your CI/CD secrets management

What Tokens Can Do

API tokens have the same permissions as an admin:

• Read secrets from all environments
• Write secrets to all environments
• Cannot manage team members or settings

Audit Trail

All token usage is logged:

{
  "action": "secret.accessed",
  "actor": "Service Account",
  "actorId": "token_xxx",
  "source": "api",
  "ip": "203.0.113.42",
  "timestamp": "2026-02-15T10:30:00Z"
}

Token Rotation

Rotate tokens regularly for security:

1. Go to team settings → API Tokens
2. Click Rotate next to the token
3. Copy the new token
4. Update your CI/CD secrets
5. The old token is immediately invalidated

TIP

Rotation generates a new token with the same name. Update your configurations promptly.

Token Revocation

If a token is compromised or no longer needed:

1. Go to team settings → API Tokens
2. Click Revoke next to the token
3. Confirm revocation

WARNING

The token stops working immediately. Any pipelines using it will fail until updated with a new token.

Troubleshooting

"Invalid token"

• Verify the token is correct (no extra spaces)
• Check if the token was revoked
• Ensure VARSAFE_API_TOKEN (or VARSAFE_TOKEN) is set correctly

"Token not authorized"

• The token may have been created for a different team
• Check if the project belongs to the token's team

"Rate limited"

API tokens share rate limits:

• 1000 requests per minute per team

If you need higher limits, contact support.

Multiple Environments

For different environments, you can either:

Option 1: One token, specify environment

# Same token, different -e flag
varsafe run -p my-api -e staging -- ./deploy.sh
varsafe run -p my-api -e production -- ./deploy.sh

Option 2: Separate tokens per environment

Create distinct tokens for staging vs production for better audit separation.

TIP

For most teams, a single token per CI/CD platform works well. Use separate tokens when you need clear audit separation between environments.

Security Checklist

• [ ] Tokens stored in CI/CD secrets, not in code
• [ ] Each pipeline has its own token
• [ ] Unused tokens are revoked
• [ ] Token rotation scheduled (every 90 days)
• [ ] Audit logs reviewed regularly