CreateSsoToken

Create a single use, client or user single sign-on access token

Tokens are valid for a maximum of 60 seconds.

WARNING: The token returned provides complete authentication to the associated client account. It is imperative that scripts ensure the actor who triggers this API call and receives this data has verified their identity and ownership for the associated account. IE, the invocation of this API should be behind your own user authentication and account mapping engine.

NOTE: The associated endpoint where this token is redeemed is only for one-time trusted tokens and will not attempt to enforce captcha or 2FA authorization controls common to the WHMCS login form.

A valid destination is expressed using the short term like "clientarea:services". Possible destinations are documented at https://go.whmcs.com/1989/single-sign-on-customization

Request Parameters

Parameter	Type	Description	Required
action	string	"CreateSsoToken"	Required
client_id	int	The id of the client that should be authenticated by the resulting token	Optional
user_id	int	The id of the user that should be authenticated by the resulting token. If not provided, the owner of the requested client will be assumed.	Optional
destination	string	A single valid destination. If not provided, the destination will be the clientarea homepage	Optional
service_id	int	The id of the service for respective clientarea $destination	Optional
domain_id	int	The id of the service for respective clientarea $destination	Optional
sso_redirect_path	string	Custom relative path for redirection after authentication when using sso:custom_redirect destination	Optional

Response Parameters

Parameter	Type	Description
result	string	The result of the operation: success or error
access_token	string	A OTP token to authenticate the user at the single sign-on endpoint
redirect_url	string	A prepared URL for redirecting your remote system authenticated users

Example Request (CURL)

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://www.example.com/includes/api.php');
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS,
    http_build_query(
        array(
            'action' => 'CreateSsoToken',
            // See https://developers.whmcs.com/api/authentication
            'username' => 'IDENTIFIER_OR_ADMIN_USERNAME',
            'password' => 'SECRET_OR_HASHED_PASSWORD',
            'client_id' => '1',
            'destination' => 'clientarea:product_details',
            'service_id' => '1',
            'responsetype' => 'json',
        )
    )
);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
$response = curl_exec($ch);
curl_close($ch);

Example Request (Local API)

$command = 'CreateSsoToken';
$postData = array(
    'client_id' => '1',
    'destination' => 'clientarea:product_details',
    'service_id' => '1',
);
$adminUsername = 'ADMIN_USERNAME'; // Optional for WHMCS 7.2 and later

$results = localAPI($command, $postData, $adminUsername);
print_r($results);

Example Response JSON

{
    "result": "success",
    "access_token": "afaed4482ad1e6b75492cdd421cc458b1991a97c",
    "redirect_url": "http:\/\/example.test\/oauth\/singlesignon.php?access_token=afaed4482ad1e6b75492cdd421cc458b1991a97c"
}

Error Responses

Possible error condition responses include:

Invalid client_id
Invalid user_id
Invalid user_id for client
A valid client_id or user_id is required
Invalid destination
Token could not be provisioned: x
SSO authentication blocked for client x

Version History

Version	Changelog
7.10.0	Initial Version