API Roles
API authentication credentials can be limited to individual API actions. This enables greater control and security when connected apps and services utilize credentials to access your WHMCS.
The API Roles you define provide a authorization subset of API actions. API credentials are associated with one or more of these roles. When an API request is made, if any role provides permission to the requested action, the request will be authorized and allowed to complete.
Contents
Managing API Roles
API Roles are managed from within the Manage API Credentials page. Navigate to Setup > Staff Management > Manage API Credentials and then select the API Roles tab.
Creating Roles
Description
Click the Create API Role button to open the Role Management dialog screen. You must provide a name for your new role. You may optionally provide a description for contextual reference. The role name and description can be changed at any point in the future.
Actions
All API actions are organized in groups itemized in a sidebar. Clicking a group will expose the related actions in the center of the dialog screen. Click the checkbox next to the API action you wish to permit. Permitted actions can be changed at any point in the future.
Once 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 may update the role name, description, or permitted API actions at any time. Find the role you wish to edit in the table list. Click the associated edit button (depicted by a pencil icon) to open the Role Management dialog screen.
Update the role, description, or selected actions as needed and click Save. Any API credential that is assigned to the affected role will immediate inherit your modifications.
Deleting Roles
You may delete a role at any time. Find the role you wish to edit in the table list. Click the associated delete button (depicted by a trash bin icon). A confirmation popup will be presented where you can confirm or cancel the delete action.
Prior to system deletion, the targeted role will be unassigned from any API credential. If you recreate the role in the future it will not be automatically assigned back to those affected API credentials.
Assigning API Roles to API Credentials
Associating one or more API roles to an API credential will determine what actions are permitted when WHMCS receives an API request containing the credential's authorization details. Credentials without assigned role will effectively have no authorization. Likewise, if one or more roles are assigned yet none of the roles have any allowed API actions, all requests will be denied authorization.
Role assignment can be managed on the API Credentials tab of the Manage API Credentials page. Find the API credential you wish to modify in the table list. Click the edit action (depicted by a pencil icon) and the Credential Management dialog screen will open.
The Access Roles multi-select field will provide all roles currently defined and available for assignment
After selecting all roles you wish to be assigned 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 generated in WHMCS v7.2 and v7.3 followed a simple authorization model. Any API request would be granted full authorization provided the identifier and secret passed the authentication verification check. This is the same behavior exhibited when using an Admin username and password in all previous and current versions of WHMCS.
This simple authorization model has been removed in WHMCS v7.4 for API Credentials and replaced 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.
A one-time forward compatibility routine will be performed in the background when updating to WHMCS v7.4. This routine will identify any previously generated API credentials. If any credentials are found, the routine will perform two operations on your behalf:
- A compatibility role will be generated which has all current API actions selecting (and thus emulating the previous, simple authorization model)
- The compatibility role will be assigned to any found credentials
These operations ensure all API credential authorizations continue to function without interruption. The compatibility role has all API actions selected that are available in WHMCS v7.3. This compatibility role will not be automatically maintained since its purpose is merely to prevent immediate disruption. You may modify or remove this role as you see fit for your integrations.