voxel.hapi.authkeys.read

Obtain hAPI authentication key/secret given a Voxel username/password. This method may only be accessed via an SSL endpoint and the username/password must be sent using Basic HTTP authentication. No key, timestamp, or api_key parameters are required when calling this method. For more information, see the main hAPI documentation.

Parameters

username (required)
Voxel username, passed using Basic HTTP authentication
password (required)
Voxel password, passed using Basic HTTP authentication

Example Response

<authkey>
  <key>4eb787e0035b1314a38af2891b125b6b</key>
  <secret>29c19ac83dc1b0f98919810ad5c44e5f</secret>
  <username>myusername</username>
  <user_type>superuser</user_type>
</authkey>

Notes

This is a special hAPI method that is not subject to the standard hAPI authentication mechanism. It is only accessible via an SSL endpoint (e.g., https://api.voxel.net/). You must use Basic HTTP authentication with your Voxel username/password when calling this method, e.g.:

  https://username:password@api.voxel.net/?method=voxel.hapi.authkeys.read

without any key, timestamp, or api_sig parameters. If the username/password are correct, the method will return the hAPI key/secret pair associated with the username, which should be used for all future requests to hAPI.

Note that the key/secret are not session-based; they are persistent. You may reset them to new values using hapi.authkeys.reset if necessary. It is recommended that any non-interactive application store a hAPI key/secret for use in authentication, rather than a Voxel username/password. An interactive application may call this method to validate a login; it should then use the returned key/secret for the remainder of its lifetime (or until it requires some re-authentication).

Though this method expects authentication credentials to be set, it does not send a standard 401 Auth Required challenge. This means that, for example:

curl https://$USER:$PASS@api.voxel.net/xxxxxxxxxxxx

will work, but:

curl -u $USER:$PASS https://api.voxel.net/xxxxxxxxxx

will not. This behavior enables hAPI to work with clients, like Flash, which do not handle 401 responses.

Method Specific Error Codes

500: Method must be accessed via an SSL endpoint
This method may only be accessed from an SSL-enabled hAPI endpoint.