API Reference

The BoxVault API provides comprehensive RESTful endpoints for user management, organization control, and box repository management. This API handles authentication, authorization, and box management for the BoxVault web interface.

Table of contents

  1. Authentication
  2. Base URL
  3. OpenAPI Specification
    1. Interactive Documentation
    2. API Categories
      1. Authentication & Authorization
      2. User Management
      3. Organization Management
      4. Box Management
      5. File Operations
  4. Rate Limiting
  5. Error Handling
  6. Response Format
  7. Related APIs

Authentication

All API endpoints require authentication using JWT tokens in the x-access-token header format:

x-access-token: <jwt_token>

See the Authentication Guide for detailed setup instructions.

Base URL

The API is served from your BoxVault server:

  • HTTPS (Recommended): https://your-server:5001
  • HTTP: http://your-server:5000

OpenAPI Specification

The BoxVault API is fully documented using OpenAPI 3.0 specification.

Interactive Documentation

API Categories

The BoxVault API is organized into the following categories:

Authentication & Authorization

  • User registration and login
  • JWT token management
  • Session management
  • Password reset and recovery

User Management

  • User profile management
  • User preferences and settings
  • Account administration
  • Role-based access control

Organization Management

  • Organization creation and configuration
  • Multi-tenant organization support
  • User-organization relationships
  • Invitation management

Box Management

  • Vagrant box creation and management
  • Box versioning and provider support
  • Architecture-specific builds
  • Box metadata and descriptions

File Operations

  • Secure file upload and download
  • Range request support for large files
  • File integrity verification
  • Storage management

Rate Limiting

The API currently does not implement rate limiting, but this may be added in future versions for production deployments.

Error Handling

The API uses standard HTTP status codes and returns JSON error responses:

{
  "success": false,
  "message": "Error description"
}

Common status codes:

  • 200 - Success
  • 201 - Created
  • 400 - Bad Request
  • 401 - Unauthorized (Invalid or expired JWT token)
  • 403 - Forbidden (Insufficient permissions)
  • 404 - Not Found
  • 500 - Internal Server Error

Response Format

Successful responses follow this format:

{
  "success": true,
  "message": "Operation completed successfully",
  "data": {
    // Response data here
  }
}