Latest revision as of 13:48, 19 September 2023

In WHMCS 7.2 and later, you can generate unique API authentication credentials. This allows for better management and security for provisioning access to API connected devices and systems.

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

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

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. For more information about API credentials, see our developer documentation.

The API Roles 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.

Creating API Roles

To create an admin API role:

1. Choose the API Roles tab.
2. Click Create API Role.
3. Enter a role name and description.
   • The description is optional.
   • You can change the role name and description at any point in the future.
4. Use the left-side menu to find API permissions.
5. Check the desired API permissions.
6. 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.

Deleting Roles

To delete a role, click the Trash icon and then click Delete.

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 may create as many API credential pairs for an admin as you require. You may remove any credential pair to invalidate access and authentication attempts that are received with that identifier.

You can also alter the admin's login password without invalidating API credentials. If you disable or remove entirely an admin user, any associated API credentials will become invalid.

If your copy of the secret is lost, 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.

Creating API Credentials

To create new admin API authentication credentials:

1. Choose the API Credentials tab.
2. Click Generate New API Credential.
3. Select the admin who the new credential will authenticate.
4. Optionally, enter a description.
5. Select the desired API roles (see above).
6. Click Generate. The system will provision a unique API credential and the credential identifier and secret will display. Use these instead of the admin's username and password for API authentication.
   You must copy the Secret value at this time. If you lose this, you will need to generate a new credential pair.
7. Click Close.

The new API credential will appear in the list.

Viewing and Editing Credentials

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

To do this:

1. Click the Edit icon for the desired credential.
2. Select the desired API roles.
3. Click Save.

Associating one or more API roles to an API credential will determine the permitted actions when WHMCS receives an API request containing the credential's authorization details. Credentials without an assigned role will effectively have no authorization. If there are one or more assigned roles but none of the roles have any allowed API actions, the system will deny all requests for authorization.

Removing Admin API Authentication Credentials

You may revoke API authentication by removing a generated credential.

To remove a authentication with a given credential, find that credential in the list, click the Trash icon, and then click Delete.

Compatibility Role On Update to v7.4

API credentials that you generate in WHMCS v7.2 and v7.3 follow a simple authorization model. The system grants full authorization to any API request if the identifier and secret pass the authentication verification check. This is the same behavior that the system uses with an Admin username and password in all previous and current versions of WHMCS.

We removed this simple authorization model in WHMCS v7.4 for API Credentials and replaced it with a Role Based Access Control (RBAC) authorization model. This new model allows for both easy management and explicit authorization across all your API apps and service integrations.

The system performs a one-time forward compatibility routine in the background when updating to WHMCS v7.4. This routine will identify any previously-generated API credentials. If the system finds any credentials, the routine will perform two operations on your behalf:

• It will generate a compatibility role that has all currently-selected API actions (emulating the previous, simple authorization model).
• It will assign the compatibility role to any found credentials.

These operations ensure that all API credential authorizations continue to function without interruption. The compatibility role selects all API actions that are available in WHMCS v7.3. The system won't automatically maintain this compatibility role since its purpose is merely to prevent immediate disruption. You may modify or remove this role for your integrations.