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.

Base URL and request scoping

All API requests go to:

https://api.xnumbers.io/api

Every resource you can access through the API is scoped to your customer account. Resource paths follow the pattern /customers/{customer_slug}/<resource>, where {customer_slug} is your customer's slug — you can find it in the customer portal (it's also the identifier in your portal URL). For example, if your slug is acme, your numbers live at:

https://api.xnumbers.io/api/customers/acme/numbers

Creating your API key

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

Step 1: Access the customer portal

1. Log in to your xNumbers customer portal
2. Go to Settings → API Keys

Step 2: Generate a new API key

1. Click "Create API Key"
2. Enter a descriptive name for your key (e.g., "Production API", "Development Testing")
3. Choose the key's access level:
   • All access: Full access to everything your account can do
   • Restricted: Pick the specific permissions the key should carry (numbers, users, logs, etc.)
   • Read-only: View-only access to your resources
4. Optionally set an expiry date
5. Create the key and copy it

API keys start with the xn_ prefix (e.g., xn_live_a1b2c3...).

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 sent with every request, in one of two ways:

• Authorization: Bearer xn_... — standard Bearer authentication (recommended)
• X-API-Key: xn_... — alternative header if your client can't set Authorization

API keys passed as query parameters are not accepted.

curl -X GET https://api.xnumbers.io/api/customers/acme/numbers \
  -H "Authorization: Bearer xn_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 fetch the phone numbers assigned to your account. Replace acme with your own customer slug.

curl -X GET https://api.xnumbers.io/api/customers/acme/numbers \
  -H "Authorization: Bearer xn_YOUR_API_KEY" \
  -H "Content-Type: application/json"

A successful response contains a data array of numbers and a meta object with pagination details:

{
  "data": [
    {
      "number_id": "123e4567-e89b-12d3-a456-426614174000",
      "number": "14155550100",
      "number_type": "mobile",
      "country_code": "US",
      "status": "active",
      "capabilities": ["voice", "sms"],
      "assigned_at": "2026-01-15T10:30:00.000Z",
      "created_at": "2026-01-15T10:30:00.000Z",
      "updated_at": "2026-01-15T10:30:00.000Z"
    }
  ],
  "meta": {
    "total": 150,
    "page": 1,
    "limit": 10,
    "totalPages": 15,
    "hasNextPage": true,
    "hasPreviousPage": false
  }
}

Managing API Keys

Once you have API keys created, you can manage them from the customer portal (Settings → API Keys):

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="xn_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/api/customers/acme/numbers',
  {
    headers: {
      'Authorization': `Bearer ${apiKey}`,
      'Content-Type': 'application/json'
    }
  }
)

console.log(response.data)

API Key Permissions

When creating API keys, you choose the key's access level. A key can never do more than your own user account is allowed to do.

Access levels

• All access: The key inherits everything your account can do
• Restricted: Granular permissions for specific features and operations
• Read-only: View-only access to your resources and data

Restricted permissions

With a restricted key, you control access to specific areas:

• Numbers: View and manage your phone numbers and KYC profiles
• Users: 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

Troubleshooting Authentication

Common authentication errors

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

{
  "statusCode": 401,
  "message": "Unauthorized"
}

If your key is valid but lacks the permission for an endpoint, you'll receive a 403 Forbidden response instead:

{
  "statusCode": 403,
  "message": "You do not have permission to perform this action",
  "error": "Forbidden"
}

Common issues and solutions

Missing Authorization header

• Ensure you're including the Authorization: Bearer xn_YOUR_API_KEY header (or X-API-Key: xn_YOUR_API_KEY) in every request

Invalid API key format

• Check that your key starts with xn_ and you're using the correct Bearer token format
• Verify there are no extra spaces or characters in your key
• Remember that query-parameter API keys are not accepted

Expired or revoked API key

• Check the portal to see if the key is still active or has passed its expiry date
• Generate a new key if the current one has expired

Insufficient permissions (403)

• Verify that your API key carries the necessary permissions for the endpoint
• Read-only keys cannot call create/update/delete endpoints

Wrong customer slug (403 or 404)

• Ensure the {customer_slug} in the URL matches your own customer account — keys only work against your own customer's resources

Testing your authentication

Use this simple test to verify your API key is working (replace acme with your customer slug):

curl -X GET https://api.xnumbers.io/api/customers/acme/numbers \
  -H "Authorization: Bearer xn_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