API Examples

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

Table of contents

  1. TOC

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",
    "stay_logged_in": true
  }'

Response:

{
  "id": "user_id",
  "username": "username",
  "email": "email@example.com",
  "accessToken": "eyJhbGciOiJIUzI1NiIs...",
  "roles": ["ROLE_USER", "ROLE_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",
    "invitation_token": "optional-invitation-token"
  }'

Refresh Token 

curl -X POST https://boxvault.example.com/api/auth/refresh-token \
  -H "x-access-token: YOUR_CURRENT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "stay_logged_in": true }'

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 '{
    "organization": "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",
    "organization_name": "myorg",
    "invite_role": "member"
  }'

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

You can create boxes in ANY organization you’re a member of:

# Create box in organization "myorg"
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",
    "is_public": false
  }'

# Create box in a different organization "otherorg" (if you're a member)
curl -X POST https://boxvault.example.com/api/organization/otherorg/box \
  -H "x-access-token: YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "ubuntu22",
    "description": "Ubuntu 22.04 Server",
    "is_public": true
  }'

Permission Notes:

  • Any organization member can create boxes
  • You can only update/delete boxes you created
  • Org admins and owners can update/delete any box in their organizations

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 '{
    "version_number": "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",
    "default_box": 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:

    # 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 

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

Any member of the organization may create one; expiration_days is capped by auth.jwt.service_account_max_expiry_days.

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

Response:

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

Authenticate Service Account 

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

System Configuration

Check Setup Status 

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

Upload SSL Certificate

During first-run setup the certificate and the private key are uploaded one file per request, each authenticated with the setup token. The response carries the path the file was saved under, which is what goes into ssl.cert_path or ssl.key_path when the configuration is submitted.

curl -X POST https://boxvault.example.com/api/setup/upload-ssl \
  -H "Authorization: Bearer YOUR_SETUP_TOKEN" \
  -F "file=@/path/to/fullchain.pem"

Response:

{
  "path": "/etc/boxvault/ssl/fullchain.pem"
}

Test SMTP Configuration

The SMTP server, sender and credentials come from mail.config.yaml; the body names the recipient only. Admin only.

curl -X POST https://boxvault.example.com/api/mail/test-smtp \
  -H "x-access-token: YOUR_ADMIN_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "test_email": "recipient@example.com" }'

Error Handling

Common Error Responses

Every refused request answers RFC 9457 problem details as application/problem+json: type is a URI under https://auth.startcloud.com/probs/, title its human summary, status the HTTP status, and errors[] one entry per failing value with a JSON Pointer into the body as sent. detail is for logs; the UI translates from rule and params.

Role-Based Access Errors:

{
  "type": "https://auth.startcloud.com/probs/forbidden",
  "title": "You may not do this.",
  "status": 403,
  "errors": []
}

Authentication Errors:

{
  "type": "https://auth.startcloud.com/probs/authentication",
  "title": "Sign in to continue.",
  "status": 401,
  "errors": []
}

Upload Errors:

{
  "type": "https://auth.startcloud.com/probs/payload-too-large",
  "title": "The upload is larger than this server accepts.",
  "status": 413,
  "errors": []
}

Validation Errors:

{
  "type": "https://auth.startcloud.com/probs/validation",
  "title": "The request did not pass validation.",
  "status": 422,
  "errors": [
    {
      "pointer": "/name",
      "rule": "pattern",
      "params": { "pattern": "slug" },
      "detail": "name must match slug"
    },
    {
      "pointer": "/version_number",
      "rule": "pattern",
      "params": { "pattern": "identifier" },
      "detail": "version_number must match identifier"
    }
  ]
}

A taken value answers 409 with type conflict and one unique entry whose params.scope names the scope it collided in; a body that could not be read answers 400 with type bad-request; a rate-limited request answers 429 with type throttled and a Retry-After header.

HTTP Status Codes

  • 200 OK - Request succeeded
  • 201 Created - Resource created successfully
  • 400 Bad Request - The body could not be read
  • 401 Unauthorized - Missing or invalid authentication
  • 403 Forbidden - Insufficient permissions
  • 404 Not Found - Resource not found
  • 409 Conflict - A value is already taken in its scope
  • 413 Payload Too Large - Upload larger than box_max_file_size
  • 422 Unprocessable Content - A value breaks a rule
  • 429 Too Many Requests - Rate limited, retry after Retry-After
  • 500 Internal Server Error - Server error

Complete API Reference

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