API Authentication Guide

Secure authentication is the foundation of API usage. This guide covers how to generate and manage API tokens, authenticate requests, and follow security best practices to protect your account.

How API Authentication Works

The {{COMPANY_NAME}} API uses Bearer token authentication (also known as token-based auth). Each request must include a valid API token in the HTTP Authorization header. The token identifies your account and determines what actions you are permitted to perform.

Generating an API Token

Step 1: Access API Settings

1. Log in to your {{COMPANY_NAME}} client portal at {{SUPPORT_URL}}
2. Navigate to Account Settings > API Access (or Security > API Tokens)
3. Click Generate New Token

Step 2: Configure Token Permissions

1. Enter a descriptive name for the token (e.g., "WordPress Plugin", "Billing Integration")
2. Select the permissions (scopes) the token should have:

- domains:read — View domain information

- domains:write — Register, renew, and manage domains

- dns:read — View DNS records

- dns:write — Create, update, delete DNS records

- hosting:read — View hosting services

- hosting:write — Manage hosting services

- account:read — View account profile and invoices

- account:write — Update account settings

1. Optionally set an expiration date

Step 3: Copy and Store the Token

1. Click Create Token
2. The token will be displayed once — copy it immediately
3. Store it securely (password manager, encrypted file, or secrets manager)

Tip: If you lose a token, you cannot retrieve it. Generate a new one and revoke the old token.

Using the Token

In HTTP Headers

Include the token in every API request:

curl -X GET https://api.{{COMPANY_NAME}}.com/v1/domains \\
  -H "Authorization: Bearer YOUR_API_TOKEN"

In Programming Languages

Python (requests library):

import requests

headers = {
    "Authorization": "Bearer YOUR_API_TOKEN",
    "Content-Type": "application/json"
}

response = requests.get(
    "https://api.{{COMPANY_NAME}}.com/v1/domains",
    headers=headers
)

Node.js (fetch):

const response = await fetch("https://api.{{COMPANY_NAME}}.com/v1/domains", {
  headers: {
    "Authorization": "Bearer YOUR_API_TOKEN",
    "Content-Type": "application/json"
  }
});

PHP (cURL):

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://api.{{COMPANY_NAME}}.com/v1/domains");
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Authorization: Bearer YOUR_API_TOKEN",
    "Content-Type: application/json"
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);

Managing Tokens

Viewing Active Tokens

1. Go to Account Settings > API Access
2. View a list of all active tokens with their names, creation dates, and last used timestamps

Revoking a Token

1. Go to Account Settings > API Access
2. Find the token you want to revoke
3. Click Revoke or the delete icon
4. Confirm the revocation

Revoked tokens are immediately invalidated and cannot be used for any further requests.

Tip: Revoke tokens immediately if you suspect they have been compromised, or when a team member leaves your organization.

Security Best Practices

1. Principle of Least Privilege

Create tokens with only the permissions they need. A token for DNS updates should not have domain registration permissions.

2. Use Environment Variables

Never hardcode tokens in your source code:

# Store in environment variable
export API_TOKEN="your-token-here"

# Use in your application
curl -H "Authorization: Bearer $API_TOKEN" ...

3. Never Commit Tokens to Version Control

Add credential files to .gitignore:

.env
*.key
config/secrets.*

4. Rotate Tokens Regularly

• Generate new tokens every 90 days
• Revoke old tokens after confirming new ones work
• Use expiration dates when creating tokens

5. Use Separate Tokens Per Application

Create different tokens for each application or integration. This limits blast radius if one token is compromised.

6. Monitor Token Usage

Review the "last used" timestamps on your tokens regularly. Investigate any unexpected usage.

7. IP Allowlisting

If available, restrict tokens to specific IP addresses for production systems.

Troubleshooting

401 Unauthorized Response

• Verify the token is correct and has not been revoked
• Ensure the Authorization header format is exactly Bearer YOUR_TOKEN (note the space after Bearer)
• Check that the token has not expired

403 Forbidden Response

• The token lacks the required permissions for the endpoint
• Generate a new token with the correct scopes

Token Not Working After Generation

• Ensure no extra whitespace or newline characters in the token
• Verify you copied the complete token string

Related Articles

• Getting Started with the API
• Managing DNS Records

Need help with API authentication? Contact our support team at {{SUPPORT_EMAIL}} or open a ticket at {{SUPPORT_URL}}.