Skip to main content

How to Use API Key Authentication to Simplify API Access

· 7 min read
Vladimir Gorobets
Vladimir Gorobets
Software Engineer

API Keys provide a secure and straightforward way to authenticate your applications when interacting with Wildix APIs. This guide walks you through creating, managing and using API Keys effectively.

Table of Contents​

What are API Keys?​

API Keys are authentication tokens that allow your applications to securely access Wildix services. They're ideal for:

  • Server-to-server integrations: connect backend systems
  • Automated scripts and workflows: scheduled tasks and automation
  • Third-party applications: external integrations
  • Background services: long-running processes

Supported APIs​

Currently Available (October 2025)​

Coming Soon​

Getting Started​

Prerequisites​

  • PBX Version: WMS 7.04.20250929.2 or higher
  • Admin Access: you must be a root admin of your company
  • WMS Access: rights to log into WMS

Creating Your First API Key​

Step 1: Access the API Keys Management​

  1. Log into WMS as root admin
  2. Navigate to PBX → Integrations → Company API Keys
  3. Click "Create New API Key"

Step 2: Configure Your API Key​

Fill in the required details:

  • Name: use a descriptive name that identifies the purpose

    • ✅ Good: "CRM Integration", "Analytics Dashboard readonly", "Users full access"
    • ❌ Avoid: "Key1", "Test", "MyKey"

  • Scopes: select the minimum permissions your application requires

    • Consult Understanding Scopes for detailed guidance
    • Start with specific operation scopes for better security

  • Expiration: choose an appropriate expiration period (1 hour to 1 year)

    • Development: 1-7 days
    • Testing: 1-30 days
    • Production: 30-365 days

Step 3: Save and Secure Your Key​

  1. Click "Create API Key"
  2. ⚠️ Important: Copy and save the API key value immediately
  3. Store securely: The key won’t be displayed again, so store it securely in a password manager or environment variables

💡 Pro Tip: For detailed management instructions, consult How to Create and Manage Company API Keys

API Key Format​

Your API key follows a standardized format:

wsk-v1-AbC123XyZ789...

Key Characteristics:

  • Prefix: always starts with wsk-v1-
  • Length: 100 characters
  • Content: secure random alphanumeric characters
  • Version: v1 indicates the current key format version

Understanding Scopes​

Scopes define what your API key can access. Wildix uses a hierarchical scope system with four levels of granularity, structured from most to least permissive:

1. Global Scope (*:*) 🚨​

  • Highest priority - overrides all other scopes
  • Full access to all APIs and operations
  • ⚠️ Development only - never use it in production
  • Maximum TTL: 7 days (enforced security limit)

⚠️ Security Warning: Global scope provides unrestricted access. Use only for development and testing.

2. Namespace Scopes (namespace:*)​

  • Service-level access to all operations within a specific API
  • Examples: messaging:*, users:*, company:*
  • Use when: you need complete access to a service
  • Good for: comprehensive integrations with specific services

3. Virtual Read Scopes (namespace:read) 🔍​

  • Read-only access to all operations in a namespace
  • Examples: messaging:read, users:read, company:read
  • Use when: you only need to retrieve data, not modify it
  • Most secure for data consumption scenarios

4. Operation Scopes (namespace:operation) 🎯​

  • Granular permissions for individual operations
  • Examples: messaging:SendMessage, users:GetUserInfo, company:GetCompanyInfo
  • Most secure - grants access only to specific functions
  • Best practice for production applications

Scope Priority and Resolution​

When multiple scopes are present, Wildix follows this priority order:

  1. Global (*:*): overrides everything
  2. Namespace (namespace:*): overrides read and operation scopes for that namespace
  3. Virtual Read (namespace:read) - overrides operation scopes for read operations
  4. Operation (namespace:operation) - most specific, lowest priority

Finding Supported Scopes​

Each API operation that supports API Key authentication includes an "Allowed Auth Scopes" section in our documentation.

Example: Conversations ListChannels supports these scopes:

  • messaging:ListChannels - specific operation scope
  • messaging:read - virtual read scope (covers all read operations)

How to find scopes for any operation:

  1. Navigate to the API documentation
  2. Find your desired operation
  3. Look for the "Allowed Auth Scopes" section
  4. Choose the most restrictive scope that meets your needs

Using Your API Key​

Authentication Method​

Include your API key in the Authorization header using Bearer token format:

Authorization: Bearer wsk-v1-your-api-key-here

cURL Example​

curl -X GET "https://api.x-bees.com/v2/conversations/channels/" \
  -H "Authorization: Bearer wsk-v1-your-api-key-here" \
  -H "Content-Type: application/json"

JavaScript/Node.js Example​

const apiKey = 'wsk-v1-your-api-key-here';
const baseURL = 'https://api.x-bees.com/v2';

async function getChannels() {
  try {
    const response = await fetch(`${baseURL}/conversations/channels/`, {
      method: 'GET',
      headers: {
        'Authorization': `Bearer ${apiKey}`,
        'Content-Type': 'application/json'
      }
    });
    
    if (!response.ok) {
      const errorData = await response.json().catch(() => ({}));
      throw new Error(`API request failed: ${response.status} - ${errorData.message || response.statusText}`);
    }
    
    return await response.json();
  } catch (error) {
    console.error('API request error:', error.message);
    throw error;
  }
}

// Usage
getChannels()
  .then(channels => console.log('Channels:', channels))
  .catch(error => console.error('Failed to get channels:', error.message));

Python Example​

import requests
import os
from typing import Dict, Any

# Load API key from environment variable (recommended)
api_key = os.getenv('WILDIX_API_KEY', 'wsk-v1-your-api-key-here')
base_url = 'https://api.x-bees.com/v2'

def make_api_request(endpoint: str, method: str = 'GET', data: Dict[str, Any] = None) -> Dict[str, Any]:
    """Make a request to Wildix API with proper error handling."""
    
    headers = {
        'Authorization': f'Bearer {api_key}',
        'Content-Type': 'application/json'
    }
    
    url = f'{base_url}/{endpoint.lstrip("/")}'
    
    try:
        response = requests.request(method, url, headers=headers, json=data, timeout=30)
        response.raise_for_status()  # Raises HTTPError for bad responses
        return response.json()
    
    except requests.exceptions.HTTPError as e:
        print(f'HTTP Error {response.status_code}: {response.text}')
        raise
    except requests.exceptions.RequestException as e:
        print(f'Request Error: {e}')
        raise

# Usage examples
try:
    # Get channels
    channels = make_api_request('conversations/channels/')
    print('Channels:', channels)
    
    # Get user info (if you have the right scopes)
    # user_info = make_api_request('users/me/')
    # print('User Info:', user_info)
    
except Exception as error:
    print(f'Failed to make API request: {error}')

Environment Variables Setup​

For security, always store API keys in environment variables:

# .env file (never commit this file)
WILDIX_API_KEY=wsk-v1-your-actual-api-key-here

# Shell export
export WILDIX_API_KEY="wsk-v1-your-actual-api-key-here"

Best Practices​

🔒 Security Best Practices​

Key Storage and Management​

  • Never commit API keys to version control: use .gitignore for .env files
  • Use environment variables: store keys outside your codebase
  • Implement key rotation: replace keys before expiration
  • Create separate keys for different environments (dev, staging, prod)
  • Use password managers or secure vaults for key storage
  • Monitor key usage: track and audit API key activity

Access Control​

  • Apply principle of least privilege: grant minimum required scopes
  • Avoid global scope (*:*) in production environments
  • Prefer read scopes when write access isn't needed
  • Regular access reviews: audit and remove unused keys

🎯 Scope Selection Strategy​

Development Phase​

  1. Start with specific operation scopes - namespace:operation
  2. Test with minimal permissions: add scopes as needed
  3. Document required scopes for future reference

Production Deployment​

  1. Use most restrictive scopes that meet requirements
  2. Prefer virtual read scopes (namespace:read) for data consumption
  3. Avoid namespace wildcards (namespace:*) unless necessary
  4. Regular scope audits: remove unused permissions

📋 Key Management Lifecycle​

Creation​

  • Use descriptive, meaningful names (e.g., "CRM-Integration-Prod")
  • Set appropriate expiration periods:
    • Development: 1-7 days
    • Testing: 7-30 days
    • Production: 30-365 days
  • Document key purpose and required scopes

Maintenance​

  • Monitor expiration dates: set calendar reminders
  • Track key usage: identify unused keys
  • Update scopes as requirements change
  • Maintain key inventory: document all active keys

Retirement​

  • Rotate before expiration, don't wait until the last minute
  • Test new keys before deactivating old ones
  • Clean up unused keys: delete immediately after replacement
  • Update documentation: reflect current key status

Need more help? Contact Wildix Support or check our Developer Documentation for additional resources.