Difference between revisions of "API Roles"
(→Editing Roles) |
|||
| Line 1: | Line 1: | ||
| − | <div class="docs-alert-info"><i class="fa fa-question-circle"></i> | + | <div class="docs-alert-info"><i class="fa fa-question-circle"></i>We added this feature in version 7.4.</div> |
| − | API authentication credentials can | + | 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 [https://developers.whmcs.com/api/authentication/#authenticating-with-api-credentials our developer documentation]. |
| − | The API Roles you define provide a authorization subset of API actions. API credentials are | + | The API Roles you define provide a authorization subset of [https://developers.whmcs.com/api/ 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== | ==Managing API Roles== | ||
| − | 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. | ||
[[File:API_Role_tab.png|550px]] | [[File:API_Role_tab.png|550px]] | ||
| Line 12: | Line 13: | ||
===Creating Roles=== | ===Creating Roles=== | ||
====Description==== | ====Description==== | ||
| − | Click the ''Create API Role'' button to open the ''Role Management'' | + | 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==== | ====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. | |
[[File:API_Role_manage_action2.png|550px]] | [[File:API_Role_manage_action2.png|550px]] | ||
| − | + | 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=== | ===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. | |
[[File:API_Role_show_detail.png|550px]] | [[File:API_Role_show_detail.png|550px]] | ||
| − | You may update the role name, description, or permitted API actions at any time. | + | 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. |
[[File:API_Role_table_edit2.png|550px]] | [[File:API_Role_table_edit2.png|550px]] | ||
| − | Update the role, description, or selected actions | + | Update the role, description, or selected actions and click ''Save''. Any API credential for the affected role will immediately inherit your modifications. |
===Deleting Roles=== | ===Deleting Roles=== | ||
| − | You may delete a role at any time. | + | 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. |
[[File:API_Role_table_delete2.png|550px]] | [[File:API_Role_table_delete2.png|550px]] | ||
| − | Prior to | + | 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== | ==Assigning API Roles to API Credentials== | ||
| − | Associating one or more API roles to an API credential will determine | + | 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. | |
[[File:API_Cred_table_edit.png|750px]] | [[File:API_Cred_table_edit.png|750px]] | ||
| − | The ''Access Roles'' multi-select field will provide all | + | The ''Access Roles'' multi-select field will provide all currently-defined roles that are available for assignment. |
[[File:API_Cred_multiselect.png|550px]] | [[File:API_Cred_multiselect.png|550px]] | ||
| − | After selecting all roles you | + | 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. |
<span id="compat" ></span> | <span id="compat" ></span> | ||
| Line 57: | Line 58: | ||
==Compatibility Role On Update to v7.4== | ==Compatibility Role On Update to v7.4== | ||
| − | API credentials | + | 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 all API credential authorizations continue to function without interruption. | + | 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. |
| − | <div class="docs-alert-warning"> | + | <div class="docs-alert-warning">We recommend creating and assigning targeted API roles that individually, and collectively, limit authorization for integrations. The continued use of a role that provides unrestricted authorization may expose unnecessary security risks.</div> |
Revision as of 15:45, 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.
Contents
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.
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.