We have a newer web site! Visit axcrypt.net instead!

Xecrets REST API

Introduction

The Xecrets Online Password manager is available via the Web using any standard browser, and now there is a beta version of an Xecrets Android App providing read-only access.

To further increase the availability, we're now publishing a simple RESTful API that allows anyone with the appropriate skills to write programs and apps to access the Xecrets service.

The following describes the API in programmer terms.

The main methods, List and Secret and their URL:s

There are two methods:

  • https://www.axantum.com/Xecrets/RestApi.ashx/list
  • https://www.axantum.com/Xecrets/RestApi.ashx/secret/{guid}

Note that HTTPS is required. Any attempt to access via HTTP will report an error. You MUST validate that the received certificate is valid.

The additional state that is required is to identify the user. This is sent as credentials for the HTTP Basic Authentication Scheme.

The username part is simply the e-mail adress the user has registered with the Xecrets server.

The password part of the credential must be preprocessed to be the Base64 encoding of the UTF-8 encoding of the Unicode coded password / passphrase string. Note that this is in addition to the Base64 encoding mandated by the scheme itself. In other words, before providing the password to the client software to package as credentials for the basic authentication scheme, the client software must first derive the bytes of the UTF-8 encoded representation of the password, and then Base64 encode it. The reason for this is to definitively define the encoding of the password, and bypass any restrictions or unclear parts of the HTTP specification and allowed characters and encoding of the HTTP headers themselves.

The service will accept pre-authentication by the client, otherwise it will respond with a WWW-Authenticate challenge. Pre-authentication is recommended to keep latency as low as possible. Please note that this makes it crucial that the client software validates the certicate provided by the server.

All responses are JSON encoded.

Common resonse structure

All responses share some fields.
  • int S
  • string M

The integer 'S' represents an error code, where '0' means 'Success'.

The string 'M' represents a textual version of the error code, human readable in english but not intended to be displayed to end-users but rather for the client software internal logging and debugging.

The Title and Content data may be processed before retrieval, so it may not look identical to the view via the web browser. Specifically partial URL:s are expanded to complete URL:s with HTTP as scheme. This facilitates for the client software to provide links to the user.

List response structure

  • TitleContent[] TCL

Each entry in the TitleContent array, TCL, has the following members:

  • string T
  • string C
  • guid G

The string 'T' represents the Title field of one record, or 'secret'.

The string 'C' represents the Content field of one record.

The guid 'G' represents a standard GUID identifying the record.

Secret response structure

  • string T
  • string C
  • string X

The string 'T' represents the Title field of the record requested.

The string 'C' represents the Content field of the record requested.

The string 'X' represents the Secret (or password) field of the record requested.

Final consderations

Client software is recommended not to cache the 'X' field, and ask for it from the server upon request by the user. The client software must also in general take care with the data it receives on behalf of the user. This applies particularily to the master password. The actual measures will vary from platform to platform.

The authentication mechanism is under the same restrictions as the web browser interface, and any attempts to automate dictionary attacks via this API will not work any more than script-based attacks on the web browser interface will.

Developers may contact Axantum Software AB for reasonable amounts of support.

The API is still in development, and may change without notice, so please let us know if you are working with it, so we can put you on a notification list. We're of course also very interested in any feedback and ideas you may have.