Security

API Tokens

API tokens authenticate your CI/CD pipelines, SDKs, and CLI against the Vizzly API. Each token is scoped to a single project.

Token Format

Tokens start with vzt_ followed by a 64-character hex string. The full token is shown once at creation. After that, you’ll only see the first 7 characters (the prefix).

Create a Token

1. Go to Settings → [Project Name]

2. Find the Access & Security section

3. Click Create Token

4. Give it a descriptive name (e.g., “GitHub Actions”, “Production SDK”)

5. Optionally set an expiration date

6. Copy the full token value - this is the only time you’ll see it

You need admin or owner permissions to create tokens. Your primary email must be verified first.

Token Storage

Tokens are hashed using SHA-256 before storage. The server never stores the plain token value. This means:

• Lost tokens can’t be recovered
• Compromised database access won’t expose tokens
• You need to create a new token if you lose one

Usage Tracking

The dashboard shows:

• Token name and prefix
• Last used timestamp
• Active/inactive status
• Expiration date (if set)

Tokens update their “last used” timestamp on each request.

Expiration

Set an expiration date when creating a token. Expired tokens stop working immediately. This is useful for:

• Temporary CI/CD access
• Time-boxed integrations
• Security compliance requirements

Deactivate or Delete

Inactive tokens remain visible but stop authenticating requests. Delete tokens you no longer need - deletion is permanent.

Rate Limiting

The API enforces rate limits per token to prevent abuse and ensure service stability.

Standard endpoints: 300 requests/minute per token Write operations: 100 requests/minute per token (future use)

When you hit the limit, requests return HTTP 429 with:

{
  "error": "Rate limit exceeded",
  "message": "Too many requests. Limit: 300 requests per 60 seconds",
  "retryAfter": 60
}

Response headers show your current limit status:

• X-RateLimit-Remaining: Requests left in current window
• X-RateLimit-Reset: When the limit resets

Project Privacy

Projects can be public or private. Configure this in Settings → [Project Name] → Access & Security.

Private projects (default):

• Only team members can view builds and comparisons
• Requires authentication to access

Public projects:

• Anyone with the link can view builds and comparisons
• No authentication required for read-only access
• Cannot be enabled if your organization is private

The public setting affects:

• Build detail pages
• Comparison views
• Screenshot URLs
• Embedded content

Team member permissions still apply for write operations (approvals, comments, etc.).

Authentication

User Accounts

Passwords are hashed with bcrypt (8 rounds) before storage. Password requirements:

• At least 8 characters
• One lowercase letter
• One uppercase letter
• One number
• One special character

OAuth Sign-In

Google OAuth is available for account creation and login. OAuth tokens are stored encrypted using AES-256-CBC with PBKDF2 key derivation (100,000 iterations).

Session Management

User sessions use JWT tokens:

• Access tokens: 15 minutes
• Refresh tokens: 7 days

Tokens include issuer and audience claims for validation. The server rejects tokens with:

• Invalid signatures
• Wrong issuer/audience
• Expired timestamps

Email Verification

Certain operations require a verified primary email:

• Creating builds
• Generating API tokens
• Administrative actions

Verification tokens expire after 7 days.

Data Protection

Encryption

Sensitive data uses AES-256-CBC encryption:

• OAuth tokens
• GitHub webhook secrets
• Other credentials

The encryption implementation uses:

• Random IVs (16 bytes) per encryption
• PBKDF2 for key derivation (100,000 iterations, SHA-512)
• Random salts (64 bytes) per encryption

Webhook Signatures

GitHub webhooks are verified using HMAC-SHA256 signatures. The server compares signatures with timing-safe equality to prevent timing attacks.

Transport Security

All API communication requires HTTPS. The server adds security headers via Helmet middleware.

Access Control

Role-Based Permissions

Organizations have three roles:

• Owner: Full control including billing
• Admin: Manage projects and settings
• Member: View and interact with builds

API Token Restrictions

API tokens cannot perform administrative actions:

• Creating/deleting projects
• Managing team members
• Changing billing settings
• Creating new tokens

Tokens are read-only for team management endpoints.

Organization Privacy

Private organizations prevent all member projects from being public. You must change organization privacy before enabling public projects.