Getting Started

This comprehensive guide will walk you through everything you need to start using the xNumbers virtual number management API. From creating your first API key to making authenticated requests and understanding security best practices - you'll be up and running in minutes.

Creating your API key

To access the xNumbers API, you'll need to create an API key from your dashboard. This key will authenticate all your API requests and provide access to your virtual number inventory.

Step 1: Access your dashboard

1. Log in to your xNumbers account at xnumbers.io
2. Navigate to your dashboard
3. Go to Settings → API Keys

Step 2: Generate a new API key

1. Click "Create New API Key"
2. Enter a descriptive name for your key (e.g., "Production API", "Development Testing")
3. Select the appropriate permissions:
   • Full Access: Complete access to all API endpoints
   • Read Only: View-only access to your resources
   • Custom: Select specific permissions for inventory, users, logs, etc.
4. Click "Generate Key"

Step 3: Secure your API key

• Store your API key in environment variables, not in your code
• Use different keys for development and production environments
• Regularly rotate your API keys for enhanced security
• Never commit API keys to version control

API Key Authentication

Your API key should be included in the Authorization header of every request using Bearer token authentication:

curl -X GET https://api.xnumbers.io/inventory \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

Making your first API request

Now that you have your API key, let's make your first request to the xNumbers API. We'll start by fetching your virtual number inventory to see what numbers are available in your account.

curl -X GET https://api.xnumbers.io/inventory \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

Managing API Keys

Once you have API keys created, you can manage them from your dashboard:

View existing keys

• See all your active API keys with their names and creation dates
• Check the last used date for each key
• View permissions assigned to each key

Rotate keys

• Generate new keys before the old ones expire
• Update your applications with the new keys
• Deactivate old keys after confirming the new ones work

Revoke keys

• Immediately disable compromised or unused keys
• Remove keys that are no longer needed
• Monitor key usage to detect unauthorized access

Security Best Practices

Protect your API keys

Security should be your top priority when working with API keys. Follow these essential practices:

• Never commit API keys to version control (Git, SVN, etc.)
• Store keys in environment variables, never in your source code
• Use different keys for development, staging, and production environments
• Rotate keys regularly for enhanced security (recommend every 90 days)
• Monitor key usage for unusual activity or unauthorized access

Environment variables

Set your API key as an environment variable in your application:

export XNUMBERS_API_KEY="your_api_key_here"

Then reference it securely in your code:

import axios from 'axios'

const apiKey = process.env.XNUMBERS_API_KEY;

const response = await axios.get('https://api.xnumbers.io/inventory', {
  headers: {
    'Authorization': `Bearer ${apiKey}`,
    'Content-Type': 'application/json'
  }
})

console.log(response.data)

API Key Permissions

When creating API keys, you can set specific permissions to limit access based on your needs:

Permission Levels

• Full Access: Complete access to all API endpoints and operations
• Read Only: View-only access to all your resources and data
• Custom: Granular permissions for specific features and operations

Custom Permissions

With custom permissions, you can control access to specific areas:

• Inventory Management: Create, update, assign, and release virtual numbers
• User Management: Create users, update roles, and manage account access
• Analytics and Reporting: Access usage statistics, costs, and detailed reports
• Call and SMS Logs: View call records, SMS logs, and communication history
• KYC Operations: Manage verification processes and document uploads

Managing API Keys

Viewing existing keys

From your dashboard, you can:

• See all your active API keys with their names and creation dates
• Check the last used date and recent activity for each key
• View the permissions and access level assigned to each key
• Monitor usage statistics and request patterns

Key rotation

Regular key rotation is crucial for security:

1. Generate a new API key with the same permissions
2. Update your applications to use the new key
3. Test that everything works with the new key
4. Deactivate the old key after confirming the new one works
5. Monitor for any failed requests using the old key

Revoking keys

Immediately revoke keys when:

• You suspect a key has been compromised or exposed
• An employee with key access leaves your organization
• You no longer need a particular key or application
• You detect unauthorized or suspicious API activity

Troubleshooting Authentication

Common authentication errors

If authentication fails, you'll receive a 401 Unauthorized response:

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid or missing API key",
    "details": "Please check your Authorization header and ensure your API key is valid"
  }
}

Common issues and solutions

Missing Authorization header

• Ensure you're including the Authorization: Bearer YOUR_API_KEY header in every request

Invalid API key format

• Check that you're using the correct Bearer token format
• Verify there are no extra spaces or characters in your key

Expired or revoked API key

• Check your dashboard to see if the key is still active
• Generate a new key if the current one has expired

Insufficient permissions

• Verify that your API key has the necessary permissions for the endpoint
• Check if you need to upgrade from Read Only to Full Access permissions

Testing your authentication

Use this simple test to verify your API key is working:

curl -X GET https://api.xnumbers.io/inventory \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -v

A successful response indicates your authentication is working correctly.

What's next?

Congratulations! You now have a comprehensive understanding of xNumbers API authentication and have made your first successful request. Here are the next steps to explore:

• Learn about virtual number inventory management
• Set up user management for your account
• Explore KYC verification processes
• View detailed analytics and usage reports
• Access call and SMS logs
• Review error handling and status codes