API Credentials

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.

For more information about using the WHMCS API, see our API Developer Documentation.

API Roles

You must create at least one API role before you can generate API credentials.

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.

For more information about using API credentials in your custom code, see Authenticating with API Credentials.

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.

The list of roles in Manage API Credentials

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.
If you lose the secret, create a new API credential pair. Then, use the newly-generated identifier and secret in your integration. Make certain to delete the previous credential pair.

Create API Credentials

You must create at least one API role before you can generate 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.
    Generating new API credentials
  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.
    The generated secret
    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 11, 2024