API Roles - Revision history

SarahK: Redirected page to Manage API Credentials

2022-02-03T21:46:23Z

Redirected page to Manage API Credentials

SarahK at 12:56, 5 August 2020

2020-08-05T12:56:03Z

SarahK: /* Managing API Roles */

2020-05-18T16:23:51Z

‎Managing API Roles

SarahK at 15:45, 18 May 2020

2020-05-18T15:45:48Z

Show changes

David: /* Editing Roles */

2017-11-06T14:38:12Z

‎Editing Roles

David: /* Deleting Roles */

2017-11-06T14:30:25Z

‎Deleting Roles

David: /* Editing Roles */

2017-11-06T14:28:34Z

‎Editing Roles

David: /* Actions */

2017-11-06T14:25:05Z

‎Actions

David: /* Compatibility Role On Update to v7.4 */

2017-10-31T13:04:45Z

‎Compatibility Role On Update to v7.4

David at 13:03, 31 October 2017

2017-10-31T13:03:58Z

← Older revision		Revision as of 21:46, 3 February 2022
Line 1:		Line 1:
−	~~<div class="docs-alert-info"><i class="fa fa-question-circle"></i>We added this feature in version 7.4.</div>~~	+	#REDIRECT [[Manage_API_Credentials]]
−
−	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 [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==~~
−
−	You can manage API Roles from within the '''Manage API Credentials''' interface. Navigate to the '''API Roles''' tab at '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > Manage API Credentials''' or, prior to WHMCS 8.0, '''Setup > Staff Management > Manage API Credentials'''.
−
−	~~[[File:API_Role_tab.png\|550px]]~~
−
−	~~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.
−
−	~~[[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===~~
−	~~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]]~~
−
−	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]]~~
−
−	~~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.
−
−	~~[[File:API_Role_table_delete2.png\|550px]]~~
−
−	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.
−
−	~~[[File:API_Cred_table_edit.png\|750px]]~~
−
−	~~The ''Access Roles'' multi-select field will provide all currently-defined roles that are available for assignment.~~
−
−	[[~~File:API_Cred_multiselect.png\|550px~~]]
−
−	~~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>~~
−
−	~~==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.
−
−	<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>

@@ Line 7: / Line 7: @@
 ==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.
+You can manage API Roles from within the '''Manage API Credentials''' interface. Navigate to the '''API Roles''' tab at '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > Manage API Credentials''' or, prior to WHMCS 8.0, '''Setup > Staff Management > Manage API Credentials'''.
 [[File:API_Role_tab.png|550px]]

← Older revision		Revision as of 16:23, 18 May 2020
Line 10:		Line 10:

	[[File:API_Role_tab.png\|550px]]		[[File:API_Role_tab.png\|550px]]
		+
		+	For more information about API Credentials, see [[API Authentication Credentials]].

	===Creating Roles===		===Creating Roles===

← Older revision		Revision as of 14:38, 6 November 2017
Line 22:		Line 22:

	===Editing Roles===		===Editing Roles===
		+	The allowed actions of a role are easy reviewed through the quick detail view. Use the expansion icon located 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]]
		+
	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.		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.

@@ Line 31: / Line 31: @@
 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]]
+[[File:API_Role_table_delete2.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.

@@ Line 24: / Line 24: @@
 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]]
+[[File:API_Role_table_edit2.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.

@@ Line 17: / Line 17: @@
 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]]
+[[File:API_Role_manage_action2.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.

@@ Line 48: / Line 48: @@
 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.

← Older revision		Revision as of 13:03, 31 October 2017
Line 51:		Line 51:
	==Compatibility Role On Update to v7.4==		==Compatibility Role On Update to v7.4==

		+	<span id="compat" ></span>
	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.		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.