You can generate unique API authentication credentials. This allows better management and security for provisioning access to API-connected devices and systems.

You can access this feature at Configuration () > System Settings > Manage API Credentials.

API Roles #

API authentication credentials can limit individual API actions. This enables greater control and security when connected apps and services use credentials to access your WHMCS.

The API roles that you define provide a authorization subset of API actions. API credentials are for one or more of these roles. When something makes an API request, if any role provides permission to the requested action, the system will authorize the request and allow it to complete.

Create an API Role #

To create an admin API role:

1. Go to Configuration () > System Settings > Manage API Credentials.
2. Go to the API Roles tab.
3. Click Create API Role.
4. Enter a role name and optional description.
5. Use the left-side menu to find API permissions.
6. Check the desired API permissions.
7. Click Save.

Viewing and Editing Roles #

You can view the API permissions for a role by clicking the arrow icon for that role in the list.

To update the role name, description, or API permissions, click the Edit icon, make the desired updates, and click Save.

Delete a Role #

To delete a role, click the Delete (trashcan) icon and then click Delete again to confirm.

When you delete a role, the system will unassign the targeted role from any API credentials. If you recreate the role in the future, the system will not automatically assign it to those affected API credentials again.

API Credentials #

You can create as many API credential pairs for an admin as you require. You may remove any credential pair to invalidate access and authentication attempts with that identifier.

• You can also alter the admin’s password without invalidating API credentials.
• If you disable or delete an admin, any associated API credentials will become invalid.

Create API Credentials #

To create new admin API authentication credentials:

1. Go to Configuration () > System Settings > Manage API Credentials.
2. Choose the API Credentials tab.
3. Click Generate New API Credential.
   
4. Select the admin who the new credential will authenticate.
5. Optionally, enter a description.
6. Select the desired API roles.
   • Credentials without an assigned role will effectively have no authorization.
   • If there are assigned roles but none of the roles have any allowed API actions, the system will deny all requests for authorization.
7. Click Generate. The system will provision a unique API credential and the credential identifier and secret will appear. Use these instead of the admin’s username and password for API authentication.
   
   You must copy the secret and store it in a safe location. If you lose this, you will need to generate a new credential pair.
8. Click Close.

Viewing and Editing Credentials #

You can update the description and associated API roles for a credential at any time.

• To only edit the description, click that description, update it, and click the checkmark icon.
• To edit the API roles for a credential, click the Edit icon, select the desired roles, and click Save.

Removing Admin API Authentication Credentials #

You may revoke API authentication by removing a generated credential.

To remove authentication with a given credential, find that credential in the list, the Delete (trashcan) icon and then click Delete again to confirm.

Last modified: June 14, 2024