Child pages
  • WHM API 1 Functions - api_token_create
Skip to end of metadata
Go to start of metadata

Description

This function creates an API token . You can use API tokens instead of a password or access hash key to execute WHM API 1 functions over HTTPS. For more information about API tokens, read our Manage API Tokens in WHM documentation.

Important:

You must call this function over an SSL connection.

Examples


 JSON API
https://hostname.example.com:2087/cpsess##########/json-api/api_token_create?api.version=1&token_name=example&expires_at=1609372800&acl-1=kill-acct&acl-2=list-accts
 XML API
https://hostname.example.com:2087/cpsess##########/xml-api/api_token_create?api.version=1&token_name=example&expires_at=1609372800&acl-1=killacct&acl-2=list-accts
 Command Line
whmapi1 api_token_create token_name=example expires_at=1609372800 acl-1=kill-acct acl-2=list-accts


Notes:

  • Unless otherwise noted, you must URI-encode values.
  • For more information and additional output options, read our Guide to WHM API 1 documentation or run the whmapi1 --help command.
  • If you run CloudLinux™, you must use the full path of the whmapi1 command:

    /usr/local/cpanel/bin/whmapi1

 Output (JSON)
{  
   "data":{  
      "name":"example",
      "token":"UWU28DCA23NKY76CN17MDPKM3O7EFQY8",
      "create_time":1483625276,
      "expires_at":"1609372800"
	  "acls":[
		 "kill-acct",
		 "list-accts"
		],
   },
   "metadata":{  
      "reason":"OK",
      "command":"api_token_create",
      "version":1,
      "result":1
   }
}
 Output (XML)
<result>
<metadata>
	<reason>OK</reason>
	<result>1</result>
	<command>api_token_create</command>
	<version>1</version>
</metadata>
<data>
	<name>example</token_name>
	<token>UWU28DCA23NKY76CN17MDPKM3O7EFQY8</token>
	<create_time>1483625276</create_time>
    <expires_at>1609372800</expires_at>
	<acls>kill-acct</acls>
	<acls>list-accts</acls>
</data>


Note:

Use WHM's API Shell interface (WHM >> Home >> Development >> API Shell) to directly test WHM API calls.

Parameters

ParameterTypeDescriptionPossible valuesExample
token_name
string

Required

The API token's name.

A valid string.

Note:

  • An API token name’s maximum length is 50 characters and the name may only contain alphanumeric characters, dashes (-), and underscores (_).
  • You must assign a name that does not already exist to the API token.
example
acl-*string

The privileges to assign to the token.

If you do not use this parameter, the system will assign all of your privileges to the token.

Note:

  • To assign multiple privileges to the token, increment the parameter name. For example: acl-1, acl-2acl-3.
  • We added this parameter in cPanel & WHM version 68.

A valid privilege that the user possesses.

Note:

You can only assign privileges that you possess to the API token.


 Click to view a list of privileges...
  • acct-summary
  • add-pkg
  • add-pkg-ip
  • add-pkg-shell
  • allow-addoncreate
  • allow-emaillimits-pkgs
  • allow-parkedcreate
  • allow-unlimited-bw-pkgs
  • allow-unlimited-disk-pkgs
  • allow-shell
  • basic-system-info
  • basic-whm-functions
  • clustering
  • cors-proxy-get
  • cpanel-api
  • cpanel-integration
  • create-acct
  • create-dns
  • create-user-session
  • demo-setup
  • digest-auth
  • edit-account
  • edit-dns
  • edit-mx
  • edit-pkg
  • generate-email-config
  • limit-bandwidth
  • list-accts
  • list-pkgs
  • locale-edit
  • mailcheck
  • manage-api-tokens
  • manage-dns-records
  • manage-oidc
  • manage-styles
  • mysql-info
  • news
  • ns-config
  • park-dns
  • passwd
  • quota
  • rearrange-accts
  • resftp
  • restart
  • show-bandwidth
  • ssl
  • ssl-buy
  • ssl-gencert
  • ssl-info
  • track-email
  • thirdparty
  • upgrade-account
  • viewglobalpackages
  • all
kill-acct
expires_atinteger

The API token's expiration time.

Important:

When an API token expires, the system does not delete it. You must manually delete expired API tokens.

If you do not use this parameter, the API token will not expire.

Note:

We added this parameter in cPanel & WHM version 82.

1609372800

Returns

ReturnTypeDescriptionPossible valuesExample
namestring

The new API token's name.

A valid token name.

Note:

Use this value to revoke an API token with WHM API 1's api_token_revoke function.

example

token



string

The new API token to use to authenticate to WHM.

A valid API token.

Warning:

Make certain that you save your API token in a safe location. You cannot access the token again after you use this function.

 Click to view...
UWU28DCA23NKY76CN17MDPKM3O7EFQY8
create_timeintegerThe API token's creation time.

A valid timestamp, in Unix Epoch format.

1483625276
expires_atstring

The API token's expiration time.

Note:

We added this return in cPanel & WHM version 82.

  • A valid timestamp, in Unix Epoch format.
  • A null value.
1609372800
aclsarray

An array of privileges that the token possesses.

Note:

We added this return in cPanel & WHM version 68.

An array of valid privileges.kill-acct