Revision as of 16:23, 18 May 2020

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.

Managing API Roles

You can manage API Roles from within the Manage API Credentials interface. Navigate to Setup > Staff Management > Manage API Credentials and then select the API Roles tab.

For more information about API Credentials, see API Authentication Credentials.

Creating Roles

Description

Click the Create API Role button to open the Role Management box. You must provide a name for your new role, and you may optionally provide a description for contextual reference. You can change the role name and description at any point in the future.

Actions

The system organizes and itemizes all API actions in groups in a sidebar. Clicking a group will expose the related actions. Check the checkbox next to the API action you wish to permit. You can change the permitted actions at any point in the future.

After you select all the actions you wish to permit for the role, click Save. The saved role will now appear in the table list.

Editing Roles

You can review the allowed actions of a role through the quick detail view. Use the expansion icon at the beginning of each row to expand or collapse the quick detail view of your configured roles.

You may update the role name, description, or permitted API actions at any time. Find the role you want to edit in the table list. Click the associated edit button (with a pencil icon) to open the Role Management screen.

Update the role, description, or selected actions and click Save. Any API credential for the affected role will immediately inherit your modifications.

Deleting Roles

You may delete a role at any time. To do this, find the role you wish to edit in the table list and click the associated delete button (with a trash bin icon). A confirmation popup will allow you to confirm or cancel the action.

Prior to deletion, 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.

Assigning API Roles to API Credentials

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.

You can manage role assignment on the API Credentials tab of the Manage API Credentials page. Find the API credential you wish to modify in the table list. Then, click the edit action (a pencil icon) and the Credential Management screen will appear.

The Access Roles multi-select field will provide all currently-defined roles that are available for assignment.

After selecting all of the roles that you want to assign to the credential, click Save. The updated assignment will be visible in the table list's respective row.

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.