Back to Home

Authentication

Learn how to authenticate your API requests using API keys.

Getting an API Key

API keys are created and managed through the Virtual Mall management portal.

How to create an API key:

  1. Go to manage.thevirtualmall.co.uk/admin/api-keys
  2. Click "Create API Key"
  3. Enter a descriptive name for your key (e.g., "Production API")
  4. Select the scopes (permissions) your application needs
  5. Click "Create API Key"
  6. Important: Copy your API key immediately - it will only be shown once and cannot be retrieved later

Security: Keep your API keys secure. Never expose them in client-side code, public repositories, or logs. If a key is compromised, delete it immediately from the management portal.

API Key Format

All API keys are prefixed with tvm_ for easy identification. A typical key looks like:

tvm_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6

Using Your API Key

Include your API key in the Authorization header of every request using the Bearer scheme:

Authorization: Bearer tvm_your_api_key_here

Example Request

cURL
curl https://api.thevirtualmall.co.uk/v1/shop \
  -H "Authorization: Bearer tvm_your_api_key_here" \
  -H "Content-Type: application/json"

Scopes (Permissions)

API keys have scopes that determine what actions they can perform. Request only the scopes your application needs.

shops:readView shop information
shops:writeUpdate your shop profile
offers:readView your offers
offers:writeCreate, update, and delete offers
vouchers:readView your vouchers
vouchers:writeCreate, update, and delete vouchers
content:readView content (news, announcements)
content:writeCreate, update, and delete content
*Full access (admin keys only)Admin

Content Review

When you create offers, vouchers, or content via the API, they are submitted with aneeds_reviewstatus. Our team will review and approve content before it goes live on The Virtual Mall.

This ensures all content meets our quality guidelines and provides accurate information to shoppers.

Authentication Errors

If authentication fails, you'll receive one of these errors:

401 Unauthorized

Missing or invalid API key

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or missing API key"
  }
}

403 Forbidden

API key is disabled, expired, or lacks required scope

{
  "success": false,
  "error": {
    "code": "FORBIDDEN",
    "message": "Missing required scope: offers:write"
  }
}