API Examples

This guide provides comprehensive examples for using the BoxVault REST API with curl commands and detailed responses.

Table of contents

  1. Authentication
    1. Sign In
    2. Sign Up
    3. Refresh Token
  2. Organizations
    1. Create Organization
    2. Send Invitation
  3. Box Management
    1. Create Box
    2. Create Box Version
    3. Create Provider
    4. Create Architecture
  4. File Operations
    1. Upload Box File
    2. Download Box File
  5. Get download link
  6. Download using returned URL
    1. Service Account Management
      1. Create Service Account
      2. Authenticate Service Account
    2. System Configuration
      1. Check Setup Status
      2. Upload SSL Certificate
      3. Test SMTP Configuration
    3. Error Handling
      1. Common Error Responses
      2. HTTP Status Codes
    4. Complete API Reference

Authentication

All authenticated endpoints require a JWT token in the x-access-token header:

curl -H "x-access-token: YOUR_JWT_TOKEN" https://boxvault.example.com/api/user

Sign In 

curl -X POST https://boxvault.example.com/api/auth/signin \
  -H "Content-Type: application/json" \
  -d '{
    "username": "YOUR_USERNAME",
    "password": "YOUR_PASSWORD",
    "stayLoggedIn": true
  }'

Response:

{
  "id": "user_id",
  "username": "username",
  "email": "email@example.com",
  "accessToken": "eyJhbGciOiJIUzI1NiIs...",
  "roles": ["user", "admin"],
  "organization": "myorg"
}

Sign Up 

curl -X POST https://boxvault.example.com/api/auth/signup \
  -H "Content-Type: application/json" \
  -d '{
    "username": "newuser",
    "email": "newuser@example.com",
    "password": "password123",
    "invitationToken": "optional-invitation-token"
  }'

Refresh Token 

# Only available if stayLoggedIn=true during signin
curl -X GET https://boxvault.example.com/api/auth/refresh-token \
  -H "x-access-token: YOUR_CURRENT_TOKEN"

Organizations

Create Organization 

curl -X POST https://boxvault.example.com/api/organization \
  -H "x-access-token: YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "myorg",
    "description": "My Organization",
    "email": "org@example.com"
  }'

Send Invitation 

curl -X POST https://boxvault.example.com/api/auth/invite \
  -H "x-access-token: YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "newuser@example.com",
    "organizationName": "myorg"
  }'

Response:

{
  "message": "Invitation sent successfully!",
  "invitationToken": "761ae0028a11ee75a02f16f702b9aa63312acfe0",
  "invitationTokenExpires": 1735467934627,
  "organizationId": 1,
  "invitationLink": "https://boxvault.example.com/register?token=761ae0028a11ee75a02f16f702b9aa63312acfe0&organization=myorg"
}

Box Management

Create Box 

curl -X POST https://boxvault.example.com/api/organization/myorg/box \
  -H "x-access-token: YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "debian12",
    "description": "Debian 12 Server",
    "isPublic": false
  }'

Create Box Version 

curl -X POST https://boxvault.example.com/api/organization/myorg/box/debian12/version \
  -H "x-access-token: YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "versionNumber": "1.0.0",
    "description": "Initial release"
  }'

Create Provider 

curl -X POST https://boxvault.example.com/api/organization/myorg/box/debian12/version/1.0.0/provider \
  -H "x-access-token: YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "virtualbox",
    "description": "VirtualBox provider"
  }'

Create Architecture 

curl -X POST https://boxvault.example.com/api/organization/myorg/box/debian12/version/1.0.0/provider/virtualbox/architecture \
  -H "x-access-token: YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "amd64",
    "defaultBox": true
  }'

File Operations

Upload Box File

Files are uploaded directly to the server using a single request. To show upload progress, use curl’s progress bar:

# Upload with progress bar and reliable transfer settings
curl --progress-bar \
  --max-time 0 \
  --connect-timeout 0 \
  --retry 5 \
  --retry-delay 10 \
  --retry-max-time 0 \
  -o upload_response.txt \
  -X POST "https://boxvault.example.com/api/organization/myorg/box/debian12/version/1.0.0/provider/virtualbox/architecture/amd64/file/upload" \
  -H "x-access-token: YOUR_JWT_TOKEN" \
  -H "Content-Type: application/octet-stream" \
  -H "X-File-Name: vagrant.box" \
  --upload-file box-file.box

Upload Options Explained:

  • --progress-bar: Show a progress bar during upload
  • --max-time 0: Disable maximum time the transfer can take
  • --connect-timeout 0: Disable connection timeout
  • --retry 5: Retry up to 5 times if the transfer fails
  • --retry-delay 10: Wait 10 seconds between retries
  • --retry-max-time 0: Disable the maximum time for retries
  • -o upload_response.txt: Save server response to file

Download Box File

BoxVault provides multiple ways to download box files:

  1. Direct browser download: 
    curl -O "https://boxvault.example.com/myorg/boxes/debian12/versions/1.0.0/providers/virtualbox/amd64/vagrant.box"
  2. Using Vagrant CLI: 
    vagrant box add "boxvault.example.com/myorg/debian12"
  3. Using download link: ```bash

    Get download link

    curl -X POST “https://boxvault.example.com/api/organization/myorg/box/debian12/version/1.0.0/provider/virtualbox/architecture/amd64/file/get-download-link”
    -H “x-access-token: YOUR_JWT_TOKEN”

Download using returned URL

curl -O “DOWNLOAD_URL”


### Get Box Metadata
```bash
curl "https://boxvault.example.com/api/organization/myorg/box/debian12/metadata"

Response:

{
  "name": "debian12",
  "description": "Debian 12 Server",
  "versions": [{
    "version": "1.0.0",
    "providers": [{
      "name": "virtualbox",
      "url": "https://boxvault.example.com/myorg/boxes/debian12/versions/1.0.0/providers/virtualbox/amd64/vagrant.box",
      "checksum_type": "sha256",
      "checksum": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
      "fileSize": "1508591037"
    }]
  }]
}

Note: File sizes are returned in bytes. To convert to GB:

const bytesToGB = (bytes) => (bytes / 1024 / 1024 / 1024).toFixed(2);
console.log(bytesToGB(1508591037)); // Outputs: "1.40"

Service Account Management

Create Service Account 

curl -X POST https://boxvault.example.com/api/service-accounts \
  -H "x-access-token: YOUR_ADMIN_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "CI/CD Service Account",
    "expirationDays": 365
  }'

Response:

{
  "id": 1,
  "username": "mark-7fb6603d",
  "token": "319b8554ee85c3df139dbbb98169b64a4b50f338968bdc145fd851eb68eff0f0",
  "expiresAt": "2025-12-28T10:51:02.000Z",
  "description": "CI/CD Service Account",
  "createdAt": "2024-12-28T10:51:02.000Z",
  "updatedAt": "2024-12-28T10:51:02.000Z",
  "userId": 1
}

Authenticate Service Account 

curl -X POST https://boxvault.example.com/api/auth/signin \
  -H "Content-Type: application/json" \
  -d '{
    "username": "mark-7fb6603d",
    "password": "319b8554ee85c3df139dbbb98169b64a4b50f338968bdc145fd851eb68eff0f0",
    "stayLoggedIn": true
  }'

System Configuration

Check Setup Status 

curl -X GET https://boxvault.example.com/api/setup/status

Upload SSL Certificate 

curl -X POST https://boxvault.example.com/api/setup/upload-ssl \
  -H "Content-Type: multipart/form-data" \
  -F "cert=@/path/to/cert.pem" \
  -F "key=@/path/to/key.pem"

Test SMTP Configuration 

curl -X POST https://boxvault.example.com/api/mail/test-smtp \
  -H "x-access-token: YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "host": "smtp.example.com",
    "port": 587,
    "secure": true,
    "auth": {
      "user": "smtp-user",
      "pass": "smtp-password"
    },
    "to": "recipient@example.com",
    "from": "sender@example.com"
  }'

Error Handling

Common Error Responses

Role-Based Access Errors:

{
  "error": "INSUFFICIENT_PERMISSIONS",
  "message": "Require Admin Role",
  "details": {
    "requiredRole": "admin",
    "currentRoles": ["user"]
  }
}

Authentication Errors:

{
  "error": "TOKEN_EXPIRED",
  "message": "JWT token has expired",
  "details": {
    "expiredAt": "2024-01-01T00:00:00Z"
  }
}

Upload Errors:

{
  "error": "CHUNK_TOO_LARGE",
  "message": "Upload chunk exceeds size limit",
  "details": {
    "maxSize": 104857600,
    "receivedSize": 157286400
  }
}

Validation Errors:

{
  "error": "VALIDATION_ERROR",
  "message": "Invalid input parameters",
  "details": {
    "name": "Only alphanumeric characters, hyphens and underscores allowed",
    "version": "Must follow semantic versioning (x.y.z)"
  }
}

HTTP Status Codes

  • 200 OK - Request succeeded
  • 201 Created - Resource created successfully
  • 400 Bad Request - Invalid parameters
  • 401 Unauthorized - Missing or invalid authentication
  • 403 Forbidden - Insufficient permissions
  • 404 Not Found - Resource not found
  • 408 Request Timeout - Upload timeout
  • 409 Conflict - Resource already exists
  • 413 Payload Too Large - Upload chunk too large
  • 500 Internal Server Error - Server error
  • 507 Insufficient Storage - Not enough storage space

Complete API Reference

For the complete API reference with all endpoints, parameters, and responses, visit: