Logging in & system info

Three small methods: checking a username and password, marking a session logged out, and reading back the installed version.

Every method on this and the following pages needs the API switched on first, under Settings > REST/XML-API — that's also where Allow_API, whether GET requests are allowed, hash checking, the response format, and the API Secret Key used to sign every call are set. See Administration & API's overview for what each of those switches does.

Settings page, REST/XML-API card: API enabled, Allow GET requests, Disable hash checking, Response as text/xml and Allow Resellers to use Admin Quick Forward Rules dropdowns, plus an empty API Secret Key field and a Save button. — Settings > REST/XML-API: where the API is switched on and the secret key used for every hash is set.

user_login

Checks a username and password and marks the account as logged in. This is the one method that needs no hash at all — see The API for why.

Who may call it: anyone with an account on the installation, any account type.

Also reachable as: /api/login (older route name for the same method).

Parameter	Required	Meaning
`u`	Yes	Username.
`p`	Yes	Password, plain text (over HTTPS).

Hash parameter order: none — no hash is checked for this call.

curl -X POST https://api.example.com/api/user_login \
  -d "u=admin" \
  -d "p=YOUR_PASSWORD"

Example response shape (success):

<page>
  <action>
    <name>login</name>
    <status>ok</status>
    <user_id>3031</user_id>
    <status_message>Successfully logged in</status_message>
  </action>
</page>

A wrong username or password answers the same shape with <status>failed</status> and <status_message>Login failed</status_message> — never an error about which of the two was wrong.

user_logout

Marks the account as logged out (the reverse bookkeeping of user_login — it does not invalidate a hash or a key, since the API has none to invalidate per caller).

Who may call it: anyone with an account, any account type.

Also reachable as: /api/logout.

Parameter	Required	Meaning
`u`	Yes	Username to log out.

Hash parameter order: this method has no dedicated order, so it falls back to the shared list — and u is never part of that list (see the note on the reference index). A bare logout call therefore hashes to SHA1(secret key) alone.

curl -X POST https://api.example.com/api/user_logout \
  -d "u=admin" \
  -d "hash=PLACEHOLDER_HASH"

Example response shape:

<page>
  <action>
    <name>logout</name>
    <status>ok</status>
  </action>
</page>

An unknown username answers the same shape with <status>failed</status>.

system_version_get

Returns the installed version string.

Who may call it: anyone with an account, any account type — the method only needs a valid u, not a particular role.

Also reachable as: /api/get_version.

Parameter	Required	Meaning
`u`	Yes	Username — used only to confirm the caller resolves to a real account.

Hash parameter order: no dedicated order — shared list, same as user_logout above.

curl -X POST https://api.example.com/api/system_version_get \
  -d "u=admin" \
  -d "hash=PLACEHOLDER_HASH"

Example response shape:

<page>
  <version>2.2.6</version>
</page>

Warning

If u doesn't resolve to a real account, system_version_get answers <page><status><error>Dont_be_so_smart</error></status></page> — that exact literal string, not a translated sentence. See the reference index for why a few error messages look like this.

Check

A successful user_login call returns <status>ok</status> with a numeric <user_id>. If you instead get API Requests are disabled or Incorrect hash, go back to The API — those come from the gates in front of every method, not from this one.