Manage API Credentials - Revision history

Lawrence at 13:48, 19 September 2023

2023-09-19T13:48:10Z

SarahK: /* API Credentials */

2022-04-18T14:52:12Z

‎API Credentials

SarahK at 21:29, 14 April 2022

2022-04-14T21:29:06Z

SarahK: /* Creating API Credentials */

2022-02-03T21:45:41Z

‎Creating API Credentials

SarahK: /* Creating API Credentials */

2022-02-03T21:45:32Z

‎Creating API Credentials

SarahK: /* Creating API Credentials */

2022-02-03T21:45:18Z

‎Creating API Credentials

SarahK: Created page with "In WHMCS 7.2 and later, you can generate unique API authentication credentials. This allows for better management and security for provisioning access to API connected devices..."

2022-02-03T21:44:45Z

Created page with "In WHMCS 7.2 and later, you can generate unique API authentication credentials. This allows for better management and security for provisioning access to API connected devices..."

New page

In WHMCS 7.2 and later, you can generate unique API authentication credentials. This allows for better management and security for provisioning access to API connected devices and systems.

You can create and manage API roles and credentials at '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > Manage API Credentials'''.

For more information about using the WHMCS API, see our [https://developers.whmcs.com/api/ API documentation].

== API Roles ==

<div class="docs-alert-danger">
<span class="title">Roles and Credentials</span><br />
You '''must''' create at least one API role before you can generate API credentials.
</div>

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.

=== Creating API Roles ===

To create an admin API role:

# Choose the '''API Roles''' tab.
# Click '''Create API Role'''.
# Enter a role name and description.
#* The description is optional.
#* You can change the role name and description at any point in the future.
# Use the left-side menu to find API permissions.
# Check the desired API permissions.
# Click '''Save'''.

=== Viewing and Editing Roles ===

You can view the API permissions for a role by clicking the arrow icon for that role in the list.

[[File:API_Role_show_detail.png|550px]]

To update the role name, description, or API permissions, click the '''Edit''' icon, make the desired updates, and click '''Save'''.

=== Deleting Roles ===

To delete a role, click the '''Trash''' icon and then click '''Delete'''.

When you delete a role, 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.

== API Credentials ==

You may create as many API credential pairs for an admin as you require. You may remove any credential pair to invalidate access and authentication attempts that are received with that ''Identifier''.

Furthermore, you may alter the admin's login password freely without invalidating credentials provisioned by this feature. If you disable or remove entirely an admin user, any associated API credentials will become invalid. As noted above, if your copy of the ''Secret'' is forgot or otherwise unknown, simply create a new API credential pair, then use the freshly generated ''Identifier'' and ''Secret'' in your integration. ''We advise you promptly delete the former credential pair whose secret is unknown''

=== Creating API Credentials ===

<div class="docs-alert-danger">
<span class="title">Roles and Credentials</span><br />
You '''must''' create at least one API role before you can generate API credentials.
</div>

To create new admin API authentication credentials:

# Choose the '''API Credentials''' tab.
# Click '''Generate New API Credential'''.
# Select the admin who the new credential will authenticate.
# Optionally, enter a description.[[File:API_Cred_generate_select_admin2.png|550px]]
# Select the desired API roles (see above).
# Click '''Generate'''. The system will provision a unique API credential and the credential identifier and secret will display. Use these instead of the admin's username and password for API authentication.[[File:API_Cred_generated_pair2.png|550px]]<div class="docs-alert-warning">You must copy the Secret value at this time. If you lose this, you will need to generate a new credential pair.</div>
# Click '''Close'''.

The new API credential will appear in the list.

[[File:API_Cred_table2.png|550px]]

=== Viewing and Editing Credentials ===

You can update the description and associated API roles for a credential at any time.

<div class="docs-alert-warning">If you only want to edit the description, click that description in the list of credentials. Update the description and then click the checkmark icon.</div>

To do this:

# Click the '''Edit''' icon for the desired credential.
# Select the desired API roles.
# Click '''Save'''.

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.

===Removing Admin API Authentication Credentials===

You may revoke API authentication by removing a generated credential.

To remove a authentication with a given credential, find that credential in the list, click the '''Trash''' icon, and then click '''Delete'''.

==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 1: / Line 1: @@
 In WHMCS 7.2 and later, you can generate unique API authentication credentials. This allows for better management and security for provisioning access to API connected devices and systems.
-You can access this feature at '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > Manage API Credentials'''.
+You can access this feature at '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > API Credentials'''.
 For more information about using the WHMCS API, see our [https://developers.whmcs.com/api/ API documentation].

@@ Line 51: / Line 51: @@
 === Creating API Credentials ===
-[[File:API_Cred_generate_select_admin2.png|right|thumb|550px]]
+[[File:API_Cred_generate_select_admin2.png|right|thumb|250px]]
 <div class="docs-alert-danger">

@@ Line 51: / Line 51: @@
 === Creating API Credentials ===
-[[File:API_Cred_generate_select_admin2.png|left|550px]]
+[[File:API_Cred_generate_select_admin2.png|right|thumb|550px]]
 <div class="docs-alert-danger">

@@ Line 45: / Line 45: @@
 == API Credentials ==
-You may create as many API credential pairs for an admin as you require.  You may remove any credential pair to invalidate access and authentication attempts that are received with that ''Identifier''.
+You may create as many API credential pairs for an admin as you require. You may remove any credential pair to invalidate access and authentication attempts that are received with that identifier.
-Furthermore, you may alter the admin's login password freely without invalidating credentials provisioned by this feature.  If you disable or remove entirely an admin user, any associated API credentials will become invalid.  As noted above, if your copy of the ''Secret'' is forgot or otherwise unknown, simply create a new API credential pair, then use the freshly generated ''Identifier'' and ''Secret'' in your integration.  ''We advise you promptly delete the former credential pair whose secret is unknown''
+You can also [[Administrator Users|alter the admin's login password]] without invalidating API credentials. If you disable or remove entirely an admin user, any associated API credentials will become invalid.
 === Creating API Credentials ===
@@ Line 90: / Line 92: @@
 You may revoke API authentication by removing a generated credential.
 To remove a authentication with a given credential, find that credential in the list, click the '''Trash''' icon, and then click '''Delete'''.
 ==Compatibility Role On Update to v7.4==

@@ Line 50: / Line 50: @@
 === Creating API Credentials ===
 <div class="docs-alert-danger">
@@ Line 61: / Line 63: @@
 # Click '''Generate New API Credential'''.
 # Select the admin who the new credential will authenticate.
-# Optionally, enter a description.[[File:API_Cred_generate_select_admin2.png|550px]]
+# Optionally, enter a description.
 # Select the desired API roles (see above).
 # Click '''Generate'''. The system will provision a unique API credential and the credential identifier and secret will display. Use these instead of the admin's username and password for API authentication.[[File:API_Cred_generated_pair2.png|550px]]<div class="docs-alert-warning">You must copy the Secret value at this time. If you lose this, you will need to generate a new credential pair.</div>