Create WHMCS API credentials and API roles securely

The WHMCS API lets other systems create clients, add orders, read invoices or open tickets – for example your website's custom order form, a mobile app or an accounting sync. Every integration should get its own credentials with only the permissions it needs.

Before you start

• A full administrator account in WHMCS.
• The public IP address of the system that will call the API.
• A list of the API actions the integration needs (for example GetClients, AddOrder, GetInvoices).

Create an API role

1. Go to Configuration → System Settings → Manage API Credentials.
2. Open the API Roles tab and click Create API Role.
3. Name it after the integration, for example Website Order Form.
4. Tick only the actions required, grouped by area (Billing, Clients, Orders, Support…).
5. Click Save.

Generate credentials

1. Open the API Credentials tab and click Generate New API Credential.
2. Choose the Admin User the credential acts as. A dedicated admin user for integrations keeps the activity log clear.
3. Add a description and select the API role.
4. Click Generate. Copy the Identifier and Secret immediately – the secret is shown only once.

Restrict by IP

Go to Configuration → System Settings → General Settings → Security and add the integration's IP to API IP Access Restriction. Requests from other IPs are rejected even with valid credentials. Use an API Access Key in configuration.php only if you cannot use fixed IPs, and keep it secret.

Test a call

The API endpoint is https://billing.example.com/includes/api.php. A quick test from the allowed server:

curl -s https://billing.example.com/includes/api.php -d action=GetClients -d identifier=IDENTIFIER -d secret=SECRET -d responsetype=json -d limitnum=1

A response with "result":"success" confirms the setup. Errors explain the reason, such as an invalid IP or missing permission.

Best practices

• One credential and role per integration, never shared.
• Store secrets in environment variables or a secrets manager, not in code repositories.
• Always call the API over HTTPS.
• Rotate credentials periodically and immediately when a developer leaves.
• Review Utilities → Logs → Activity Log for actions performed by the integration user.

Revoke or rotate

On the API Credentials tab, click the credential and Delete to revoke it instantly, or generate a new one, update the integration and then delete the old one for a zero-downtime rotation.

Troubleshooting

• "Invalid IP": add the caller's public IP (check IPv6 too) to the allowed list.
• "Authentication Failed": wrong identifier or secret, or the credential was deleted.
• "Access Denied" for an action: the API role does not include it.
• Requests blocked by a WAF or Cloudflare: allow the API path for the integration's IP.

Next steps

• WHMCS security checklist.
• Admin roles and 2FA.
• Products and order links.