Authentication Guide

Learn about BoxVault authentication, JWT tokens, and API access.

Table of contents

1. Overview
2. User Authentication
   1. Web Interface Login
   2. API Authentication
   3. Using JWT Tokens
3. Token Management
   1. Token Expiration
   2. Token Refresh
   3. Token Revocation
4. User Roles and Permissions
   1. Role Hierarchy
   2. Permission Matrix
5. Service Accounts
   1. Creating Service Accounts
   2. Service Account Authentication
6. API Security
   1. Rate Limiting
   2. CORS Configuration
7. Security Best Practices
   1. Password Requirements
   2. JWT Security
   3. Account Security
8. Integration Examples
   1. CI/CD Pipeline
   2. Vagrant Plugin
9. Troubleshooting
   1. Common Issues

---

Overview

BoxVault uses JWT (JSON Web Tokens) for authentication, providing secure access to both the web interface and API endpoints.

User Authentication

Web Interface Login

1. Navigate to BoxVault web interface
2. Click “Sign In”
3. Enter username/email and password
4. Access granted with session cookie

API Authentication

Get JWT token via API:

curl -X POST http://localhost:3000/api/auth/signin \
  -H "Content-Type: application/json" \
  -d '{"username":"your-username","password":"your-password"}'

Response:

{
  "id": 1,
  "username": "your-username",
  "email": "user@example.com",
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Using JWT Tokens

Include the token in API requests:

curl -H "x-access-token: YOUR_JWT_TOKEN" \
  http://localhost:3000/api/user/profile

Token Management

Token Expiration

JWT tokens have configurable expiration times:

auth:
  jwt:
    secret: "your-secret-key"
    expiresIn: "24h"  # 24 hours

Token Refresh

Refresh expired tokens:

curl -X POST http://localhost:3000/api/auth/refreshtoken \
  -H "Content-Type: application/json" \
  -d '{"refreshToken":"YOUR_REFRESH_TOKEN"}'

Token Revocation

Logout/revoke tokens:

curl -X POST http://localhost:3000/api/auth/signout \
  -H "x-access-token: YOUR_JWT_TOKEN"

User Roles and Permissions

Role Hierarchy

1. Admin - Full system access
2. Moderator - Organization management
3. User - Basic access
4. Service Account - API-only access

Permission Matrix

Action	Admin	Moderator	User	Service Account
Create Organization	✓	✓	✗	✗
Manage Users	✓	✓ (org only)	✗	✗
Upload Boxes	✓	✓	✓	✓
Download Boxes	✓	✓	✓	✓
System Settings	✓	✗	✗	✗

Service Accounts

Creating Service Accounts

Service accounts are for API-only access:

curl -X POST http://localhost:3000/api/admin/service-accounts \
  -H "x-access-token: ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "CI/CD Pipeline",
    "description": "Automated box uploads",
    "organizationId": 1
  }'

Service Account Authentication

curl -X POST http://localhost:3000/api/auth/service-account \
  -H "Content-Type: application/json" \
  -d '{"clientId":"service-account-id","clientSecret":"service-account-secret"}'

API Security

Rate Limiting

API requests are rate limited:

• Authenticated: 1000 requests/hour
• Unauthenticated: 100 requests/hour
• File uploads: 10 uploads/hour

CORS Configuration

Configure CORS for web applications:

server:
  cors:
    enabled: true
    origin: ["https://your-app.com"]
    credentials: true

Security Best Practices

Password Requirements

• Minimum 8 characters
• Mix of uppercase, lowercase, numbers
• Special characters recommended
• No common passwords

JWT Security

• Use strong secret keys (256-bit minimum)
• Rotate secrets regularly
• Set appropriate expiration times
• Use HTTPS in production

Account Security

• Enable two-factor authentication (if available)
• Regular password changes
• Monitor login activity
• Revoke unused tokens

Integration Examples

CI/CD Pipeline

# GitHub Actions example
- name: Upload Box to BoxVault
  run: |
    TOKEN=$(curl -s -X POST $BOXVAULT_URL/api/auth/service-account \
      -H "Content-Type: application/json" \
      -d '{"clientId":"$","clientSecret":"$"}' \
      | jq -r '.accessToken')
    
    curl -X POST $BOXVAULT_URL/api/organization/myorg/box/mybox/version/1.0.0/provider/virtualbox/architecture/amd64/file \
      -H "x-access-token: $TOKEN" \
      -F "file=@mybox.box"

Vagrant Plugin

# Vagrantfile
Vagrant.configure("2") do |config|
  config.vm.box = "myorg/ubuntu-20.04"
  config.vm.box_url = "https://boxvault.example.com/api/organization/myorg/box/ubuntu-20.04"
  config.vm.box_download_options = {
    "x-access-token" => ENV['BOXVAULT_TOKEN']
  }
end

Troubleshooting

Common Issues

Invalid token:

• Check token expiration
• Verify token format
• Ensure correct header name

Permission denied:

• Check user role
• Verify organization membership
• Review resource permissions

Rate limit exceeded:

• Implement exponential backoff
• Use service accounts for automation
• Contact admin for limit increases