Authentication

Learn how to authenticate your API requests and manage your API keys securely.

All API requests to VasBox require authentication. We use API keys to authenticate requests and ensure that only authorized applications can access your data.

API Keys

API keys are used to authenticate your requests to the VasBox API. Each key is prefixed to indicate its type and environment.

PrefixTypeDescription
vb_live_Live KeyUse for production requests. Transactions are real and submitted to ZIMRA.
vb_test_Test KeyUse for development and testing. No real transactions are created.

Protect your API keys

Your API keys carry many privileges. Do not share them in publicly accessible areas such as GitHub, client-side code, or public forums.

Generating API Keys

You can generate and manage your API keys from the VasBox dashboard:

  1. Log in to your VasBox dashboard
  2. Navigate to Settings → API Keys
  3. Click Create New Key
  4. Give your key a descriptive name
  5. Copy and securely store your new key
API keys are only shown once when created. If you lose your key, you'll need to generate a new one.

Authentication Methods

VasBox supports two methods for authenticating API requests. Choose the method that best fits your use case.

Bearer Token (Recommended)

Include your API key in the Authorization header as a Bearer token:

Bash
curl -X GET https://api.vasbox.co.zw/v1/invoices \
  -H "Authorization: Bearer vb_live_abc123xyz789"

X-API-Key Header

Alternatively, you can pass your API key in the X-API-Key header:

Bash
curl -X GET https://api.vasbox.co.zw/v1/invoices \
  -H "X-API-Key: vb_live_abc123xyz789"

SDK Authentication

Our official SDKs handle authentication automatically. Simply initialize the client with your API key:

PHP
<?php

use VasBox\VasBox;

// Using environment variable (recommended)
$vasbox = new VasBox(env('VASBOX_API_KEY'));

// Or pass directly (not recommended for production)
$vasbox = new VasBox('vb_live_abc123xyz789');

// All subsequent requests are automatically authenticated
$invoices = $vasbox->invoices->list();
JavaScript
import { VasBox } from '@vasbox/sdk';

// Using environment variable (recommended)
const vasbox = new VasBox(process.env.VASBOX_API_KEY);

// All subsequent requests are automatically authenticated
const invoices = await vasbox.invoices.list();

Environments

VasBox provides two environments for different stages of your integration:

EnvironmentBase URLPurpose
Sandboxhttps://sandbox.api.vasbox.co.zwDevelopment and testing. No real ZIMRA submissions.
Productionhttps://api.vasbox.co.zwLive transactions. Real ZIMRA submissions.
Always develop and test using the sandbox environment before switching to production.

Security Best Practices

Follow these security best practices to protect your API keys and data:

Use Environment Variables

Store your API keys in environment variables, never in source code or configuration files that might be committed to version control.

Rotate Keys Regularly

Periodically rotate your API keys to minimize the impact of a potential key compromise. You can rotate keys via the API:

Bash
curl -X POST https://api.vasbox.co.zw/v1/api-keys/rotate \
  -H "Authorization: Bearer vb_live_abc123xyz789" \
  -H "Content-Type: application/json"

Use Least Privilege

Create separate API keys for different applications or services, and only grant the permissions each key needs.

Monitor API Usage

Regularly review your API usage in the dashboard to detect any unusual activity that might indicate a compromised key.

Previous Quick Start
NextInvoices