WHMCS Single Sign-On Developer Guide
WHMCS Single Sign-on allows trusted applications and third parties to authenticate users into a WHMCS installation automatically, without the user having to re-authenticate.
Our Single Sign-On implementation is based on the popular and widely used OAuth 2.0 authorization framework which outlines a secure workflow for accessing user data while protecting their account credentials.
Single Sign-on Workflow
Here's how the process works.
- The application requests an access token by sending its credentials to the OAuth Token API Endpoint
- If the application credentials check out, the WHMCS auth server will return an access token to the application
- The application then redirects the user to the Single Sign-On API Endpoint passing in the token and desired destination (scope)
- The user is authenticated and redirected to the requested destination.
Performing Single Sign-On requires an CreateOAuthCredential with the single sign-on grant type.
Supported Destinations
| Scope Name | Destination |
| clientarea:profile | My Details |
| clientarea:billing_info | Manage Billing Information/Credit Card |
| clientarea:emails | My Emails |
| clientarea:announcements | Announcements |
| clientarea:downloads | Downloads |
| clientarea:knowledgebase | Knowledgebase |
| clientarea:network_status | Network Status |
| clientarea:services | My Products/Services |
| clientarea:product_details | Product Details/Information |
| clientarea:domains | My Domains |
| clientarea:domain_details | Domain Details/Information |
| clientarea:invoices | My Invoices |
| clientarea:tickets | My Support Tickets |
| clientarea:submit_ticket | Open New Ticket |
| clientarea:shopping_cart | Shopping Cart Default Product Group |
| clientarea:shopping_cart_addons | Shopping Cart Addons |
| clientarea:shopping_cart_domain_register | Shopping Cart Register Domain |
| clientarea:shopping_cart_domain_transfer | Shopping Cart Transfer Domain |
Failure Definitions
The following are the possible error messages you may receive in working with the Single Sign-On API:
Single Sign-On authentication denied for "Closed" User ID: xx
Single Sign-On can only be performed for clients in Active or Inactive status.
Single Sign-On authentication denied per configuration for User ID: xx
Single Sign-On will not be permitted if the client has disabled it via the Security Settings of their account.
Unable to authenticate with Single Sign-On token for User ID: xx
If authentication with the given token fails for an unspecified reason.
OAuth authorization request denied due to unexpected active login session for "Closed" User ID: xx
Indicates the user has an existing active session that they are not permitted to have due to the account status being Closed.