|
|
| (11 intermediate revisions by 2 users not shown) |
| Line 1: |
Line 1: |
| − | <div class="docs-alert-info"><i class="fa fa-question-circle"></i> This feature is available in version 7.4 and above</div>
| + | #REDIRECT [[Manage_API_Credentials]] |
| − | | |
| − | 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.
| |
| − | | |
| − | ==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.
| |
| − | | |
| − | [[File:API_Role_tab.png|550px]] | |
| − | | |
| − | ===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.
| |
| − | | |
| − | [[File:API_Role_manage_action.png|550px]]
| |
| − | | |
| − | 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.
| |
| − | | |
| − | [[File:API_Role_table_edit.png|550px]]
| |
| − | | |
| − | 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.
| |
| − | | |
| − | [[File:API_Role_table_delete.png|550px]]
| |
| − | | |
| − | 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.
| |
| − | | |
| − | [[File:API_Cred_table_edit.png|750px]]
| |
| − | | |
| − | The ''Access Roles'' multi-select field will provide all roles currently defined and available for assignment
| |
| − | | |
| − | [[File:API_Cred_multiselect.png|550px]]
| |
| − | | |
| − | 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.
| |
| − | | |
| − | <div class="docs-alert-warning">WHMCS recommends creating and assigning targeted API roles which individually, and collectively, limit authorization granted to integrations. The continued use of a role which provides unrestricted authorization may expose unnecessary security risks.</div>
| |