The name.com API authentication and sandbox setup guide

Authentication is one of the first hurdles when building a name.com API integration. Using credentials for the wrong environment, constructing the Authorization header incorrectly, or attempting to use newly created development/test credentials before they are active can all prevent an otherwise valid API request from succeeding.

We use HTTP Basic Authentication to secure requests to the name.com API. Production and development/test are separate environments with separate credentials and base URLs. By the end of this guide, you'll know how to generate the credentials for each environment, construct the Authorization header correctly, choose the appropriate environment, and diagnose common authentication failures during initial setup.

How HTTP Basic Auth works in the name.com core API

Our API uses HTTP Basic Authentication, combining your username and API token into a Base64-encoded string and sending it in the Authorization header with authenticated requests. The credential string is username:api_token; the resulting Base64 value is prefixed with Basic.

The process has three steps.

First, join the username and token with a colon:

username:api_token

Next, Base64-encode that combined string. Finally, prefix the encoded value with Basic and send it in the Authorization header:

Authorization: Basic <base64-encoded-credentials>

An annotated example showing how the pieces relate:

# Your name.com API username 
username: reseller123 
# Your API token (from account settings) 
api_token: abc123tokenvalue 

# Step 1: Join with a colon 
credential_string: reseller123:abc123tokenvalue 
# Step 2: Base64-encode 
encoded: cmVzZWxsZXIxMjM6YWJjMTIzdG9rZW52YWx1ZQ== 
# Step 3: Set the Authorization header 
Authorization: Basic cmVzZWxsZXIxMjM6YWJjMTIzdG9rZW52YWx1ZQ== 

Base64 is an encoding scheme and does not encrypt or otherwise protect the credentials. Anyone who obtains the header can decode the Base64 value, which is why API credentials should only be transmitted over HTTPS. Treat your API token as a secret credential, store it in an environment variable or secrets manager, and never commit it to source control.

Generating API tokens for production and development

You can generate API tokens through your name.com account interface. The API Tokens page provides separate options for generating a Production token and a Development/Test Environment token. Generate the credentials you need for each environment and store the token values securely.

Follow these steps to generate a token:

1. Click the User icon (top right) and select Settings.
2. In the left-hand menu, click API Tokens under Secure by Design.
3. Click Create API Token.
4. Review the name.com API Access Agreement and click I Agree.
5. Enter a name for the token and click Generate new token.
   Repeat the process as needed to generate credentials for the other environment. Credentials are environment-specific: a Production token is used with the production endpoint, while a Development/Test Environment token is used with the development/test endpoint. Using a credential for the wrong environment results in an authentication error.

Two-factor authentication and API access. If your account has 2FA enabled, API access must be explicitly enabled under Settings → Security → Security Settings. Without name.com API Access enabled, requests using HTTP Basic Authentication return a 401 Unauthorized response even when the API token itself is valid. Keep 2FA enabled and enable the name.com API Access setting to use the API.

You can also optionally restrict API access to specific IP addresses by adding them to the allowlist on the API Tokens page. If IP restrictions are enabled, requests from addresses outside the allowlist will be blocked.

Sandbox vs. production environments

Our API provides two separate environments. Use production for operations against your live domains and DNS. Use development/test to build and verify your integration without affecting production resources.

The -test username suffix is required for the sandbox environment. Even if your token is correct, using your standard username against the development/test endpoint will return a 401.

We isolate the development/test environment from production in two ways that affect integration work. Domains must be created within the development/test environment before you can perform API operations against them, because domains in the production environment are not automatically available in development/test. The development/test environment is also API-only, so you verify its state through API calls.

That isolation is the whole point. You can register, configure, and delete test domains repeatedly without affecting your production account or production resources. Build and verify your integration against development/test, then switch to the production endpoint and production credentials when you're ready to go live.

Constructing authenticated requests

There are two practical ways to authenticate against the name.com API. You can let cURL construct the Basic Auth header automatically, or construct the Authorization header manually.

Option 1: cURL with -u

cURL's -u (or --user) flag accepts username:token directly and handles the Base64 encoding internally, making it the fastest path for testing.

Linux/macOS

# Production
curl -u ‘reseller123:your-production-token’ \
  https://api.name.com/core/v1/hello

# Development/Test
curl -u ‘reseller123-test:your-dev-token’ \
  https://api.dev.name.com/core/v1/hello

Windows PowerShell

# Production
curl.exe -u reseller123:your-production-token `
  https://api.name.com/core/v1/hello

# Development/Test
curl.exe -u reseller123-test:your-dev-token `
  https://api.dev.name.com/core/v1/hello

Option 2: Manual header construction

When you need to set the Authorization header explicitly—in an HTTP client, a custom script, or an integration that does not support -u—build the encoded value first, then pass it directly.

Linux/macOS (bash)

# Encode credentials
ENCODED=$(printf '%s' 'reseller123:your-production-token' | base64)

# Make the request with an explicit Authorization header
curl --request GET \
  --url https://api.name.com/core/v1/hello \
  --header "Authorization: Basic \$ENCODED"

Windows PowerShell

# Encode credentials
\$encoded = [Convert]::ToBase64String(
  [Text.Encoding]::UTF8.GetBytes("reseller123:your-production-token")
)

# Make the request with an explicit Authorization header
Invoke-RestMethod -Uri "https://api.name.com/core/v1/hello" `
  -Headers @{ Authorization = "Basic $encoded" }

The GET /core/v1/hello endpoint is a lightweight connectivity check for verifying that your API credentials and connection are working. A successful request returns HTTP 200. When you switch to the development/test environment, update both the base URL (https://api.dev.name.com) and the credentials (reseller123-test with the Development/Test Environment token).

Troubleshooting common authentication issues

1. 401 when using the wrong credentials for the environment

Symptom
The request returns 401 and you're confident the token is valid.

Cause
Production credentials were sent to the development/test endpoint, or development/test credentials were sent to the production endpoint.

Fix
Check the base URL and the credential set together. If the URL is https://api.dev.name.com, the username must end in -test and the token must be the Development/Test Environment token. If the URL is https://api.name.com, use the standard username and Production token. Using the wrong credential for the environment results in a 401.

2. 401 when the Authorization header is missing or malformed

Symptom
The request returns 401 and you're using the correct environment.

Cause
The Authorization header is absent, uses the wrong scheme (e.g., Bearer instead of Basic), or contains an incorrectly Base64-encoded value.

Fix
Verify that the header is present and formatted as Authorization: Basic <encoded-value>. The annotated example in the HTTP Basic Auth section shows exactly how the encoded value is constructed from the credential string.

3. 401 when API access is blocked by account 2FA settings

Symptom
Authentication fails even though the token was generated successfully.

Cause
The account has 2FA enabled but the name.com API Access setting hasn't been turned on. We require this additional step for accounts with 2FA active.

Fix
Go to Settings, Security in the name.com account interface and enable name.com API Access to the on position. Keeping 2FA active while enabling API Access is the correct configuration.

4. 401 when freshly generated development/test credentials won't authenticate

Symptom
You generated a Development/Test Environment token, the credentials look correct, but every request returns 401.

Cause
Newly created development/test credentials require up to 15 minutes to become active. This is a documented activation period, not a token error.

Fix
Wait 15 minutes and retry. Regenerating the token resets the activation clock. If you're still seeing 401s after 15 minutes, confirm the username suffix and token type as described in issue #1 above.

5. CORS errors from browser-based requests

Symptom
The request never reaches the API, and the browser blocks it with a CORS policy error in the console.

Cause
CORS (Cross-Origin Resource Sharing) is a browser security restriction that prevents client-side JavaScript from making direct cross-origin API calls. The browser blocks the request before your credentials are evaluated, so this is a request origin problem, not an authentication failure.

Fix
Move authenticated API calls to a server-side application or backend service. Making name.com API requests from browser JavaScript also exposes your API token in client-side code, which is a separate security problem. Use a backend that holds the token securely and proxies domain operations on behalf of your users.

Every request from here follows this pattern

Authentication for the name.com API follows a repeatable four-step process: generate the right credentials for the target environment, select the matching base URL, construct the HTTP Basic Authentication header from your username and token, and make the request. Production and development/test environments are separate, so the credential set must always match the environment; using the wrong credentials results in a 401.

When a 401 appears, check the environment and credential set first, then verify the Authorization header format, and then review your account's API Access setting under Security. If you're working in the development/test environment with newly generated credentials, allow up to 15 minutes for them to become active before troubleshooting further.

Every subsequent name.com API operation builds on the same authenticated request pattern established here. Start building for free today. For enterprise pricing and direct collaboration with the name.com team, reach out via the name.com partner contact page.