Retrieve API key

If you want to retrieve the users API key from your application. You can use the following API call.

Please note that even though we are using the users username and password to retreive the API key, we are not authenticating to the API using the users username and password. This is only to retrieve the API key. When you're saving the users credentials. Don't save the username and password and call this request every time. Save the API key, this is why it's there.

Request

Request URL: /login
Request Verb: POST
Parameters:
  user:
    email:     # String  Users email or username (if LDAP authentication is configured)
    password:  # String  The users password
Response:
  user:
    api_key:   # String  The users API key 

You can use any string that the user normally logs in with on the login page of the LiquidFiles system. If you've setup LDAP integration and are also authenticating the users sAMAccountName, you can use the users shortname instead of the email.

Example Request

<?xml version="1.0" encoding="UTF-8"?>
<user>
  <email>user@example.com</email>
  <password>password</password>
</user>

This code needs to be sent using an HTTP POST to the /login URL of your LiquidFiles system.

Example Response

<?xml version="1.0" encoding="UTF-8"?>
<user>
  <api_key>4i1Rkf3pkxu0OCRuSuTMqE</api_key>
</user>

A complete example using curl

The following shell script will retrieve the api key for the user with email user@company.com.

#!/bin/bash

email="user@company.com"
password="secret"
base_url="https://liquidfiles.company.com"

cat <<EOF | curl -k -s -X POST -H 'Content-Type: text/xml' -d @- $base_url/login
<?xml version="1.0" encoding="UTF-8"?>
<user>
  <email>$email</email>
  <password>$password</password>
</user>
EOF

A word about complex passwords:

In XML, there's quite a few characters that are not permitted. For instance, any password with a ampersand '&', a dollar '$' and many other special characters will fail with the above example code.

To get around this, you will need to escape these characters, that's basically any characters beyond a-z, A-Z and 0-9. So a password of aBcD0123&$ is encoded to: aBcD0123&$

Please see: http://www.ascii.cl/htmlcodes.htm for a list of html codes, if your language does not provide with good helper methods for this conversion.

As an alternative, you have the following options:

1. If this is a static script, you don't need this API call at all. Just grab the API key for the user in the LiquidFiles web interface. The API key doesn't change.
2. If this is for internal users that are already authenticated, you can use the API call to retreive any users API key from an admin account. Please see: Retrieve any users API key for more info.
3. Or lastly, if this script is for external users, if you can't escape users passwords properly, you will have to add a password validation to make sure the end user doesn't set passwords that won't work.