API Protocol

Registration

Registering Prekeys (first time)

This api registers your long-term identity key, your device, and the device's prekeys.

POST /api/v1/key/initial
Authorization: basic_auth

Body (application/json):
{
  lastResortKey : {
                    id : "{keyId}",
                    signature : "{signature}",
                    preKey : "{publicKey}",
                  },
  prekeys : [
              {
                id : "{keyId}",
                signature : "{signature}",
                preKey : "{publicKey}",
              },
              ...
            ]
}

1. basic_auth credentials are described here
2. keyId is an integer that is the prekey's id. It is created by the axolotl library.
3. `signature' is a base64 encoded string of the signature of the public key, signed by the client's long term identity key.
4. publicKey is a base64 encoded string from the keyPair's public array buffer

Returns:

1. 200 request succeeded.
2. 401, signature invalid authentication credentials (bad signature)
3. 401, time invalid authentication credentials (stale timestamp)
   • this response will also include the server's unix time in the header Server-Time
4. 401, registered invalid authentication credentials (identityKey & deviceId already registered)
5. 401, badly formed credentials invalid authentication credentials (basic_auth username & password missing or malformed)
6. 415 badly formatted request body.

Update Prekeys (must already be registered)

This api adds the prekeys included in the body to an already registered device

PUT /api/v1/key/update/
Authorization: basic_auth

Body (application/json):
{
  lastResortKey : {
                    id : "{keyId}",
                    signature: "{signature}",
                    preKey : "{publicKey}"
                  },
  prekeys : [
              {
                id : "{keyId}",
                signature : "{signature}",
                preKey : "{publicKey}"
              },
              ...
            ]
}

1. basic_auth credentials are described here
2. keyId is an integer that is the prekey's id. It is created by the axolotl library.
3. `signature' is a base64 encoded string of the signature of the public key, signed by the client's long term identity key.
4. publicKey is a base64 encoded string from the keyPair's public array buffer

Returns:

1. 200 request succeeded.
2. 401, signature invalid authentication credentials (bad signature)
3. 401, time invalid authentication credentials (stale timestamp)
   • this response will also include the server's unix time in the header Server-Time
4. 401, not registered invalid authentication credentials (identityKey & deviceId not registered)
5. 401, badly formed credentials invalid authentication credentials (basic_auth username & password missing or malformed)
6. 401, revoked invalid authentication credentials (identityKey revoked)
7. 415 badly formatted request body.

Adding device to identity key

Not implemented yet, but planned for future support of multi-device

POST /api/v1/key/addDevice
Authorization: basic_auth

Delete device from key server

This api removes a device and its prekeys from an associated identity key. If the last device is deleted, then the identity key is revoked.

DELETE /api/v1/key/
Authorization: basic_auth

Returns:

1. 200 request succeeded.
2. 401, signature invalid authentication credentials (bad signature)
3. 401, time invalid authentication credentials (stale timestamp)
   • this response will also include the server's unix time in the header Server-Time
4. 401, not registered invalid authentication credentials (identityKey & deviceId not registered)
5. 401, badly formed credentials invalid authentication credentials (basic_auth username & password missing or malformed)
6. 401, revoked invalid authentication credentials (identityKey revoked)

Sending Messages

Getting a recipient's PreKey

If a client does not have an existing session with a recipient, the client will need to retrieve a PreKey for the recipient in order to start one.

GET /api/v1/key/"{identity_key}"
Authorization: basic_auth

1. basic_auth credentials are described here
2. identity_key is a base64 encoded Curve25519 public key that belongs to the user who's key you are fetching. Each client should have a single identity key generated at install time. NOTE: in this context, the base64 string must be escaped and made url safe

Returns:

1. 401, signature invalid authentication credentials (bad signature)
2. 401, time invalid authentication credentials (stale timestamp)
   • this response will also include the server's unix time in the header Server-Time
3. 401, not registered invalid authentication credentials (identityKey & deviceId not registered)
4. 401, badly formed credentials invalid authentication credentials (basic_auth username & password missing or malformed)
5. 401, revoked invalid authentication credentials (identityKey revoked)
6. 404 requested identity_key not found.
7. 404 requested identity_key has been revoked.
8. 415 badly formatted request body.
9. 200 request succeeded. The body below is returned.
10. 205 request succeeded. Must produce and upload more prekeys. The body below is returned.

{
  "{deviceId}" : {
                id : "{keyId}",
                keyPair : {
                            public : "{publicKey}",
                            private : "{privateKey}"
                          }
               },
   ... 
} 

1. deviceId is the device id to which the prekey belongs. There will be a key/value pair for every device associated with the requested identity_key
2. keyId is an integer that is the prekey's id. It is created by the axolotl library.
3. publicKey is a base64 encoded string from the keyPair's public array buffer
4. privateKey is a base64 encoded string from the keyPair's private array buffer

Submitting a message

POST /api/v1/message/
Authorization: basic_auth

Body (application/json):
{
  messages: [{
               headers: [
                        {
                         recipient : "{identityKey|deviceId}", //string
                         messageHeader: "{message_header}" //string
                        },
                        ...
                       ]    
               body: "{body}", //string
             },
             ...,
            ]
}

1. The body consists of an array of messages
2. A message consists of an array of headers (one for each recipient of the message) and a body (one per message)
3. identityKey|deviceId is the concatenation of a recipient's base64 encoded long-term public key, the '|' character, and the deviceId of the device to which this message is being sent.
4. message_headeris a base64 encoded string that is unique to each recipient.
5. body is a base64 encoded string containing the encrypted message.

Returns:

1. 401, signature invalid authentication credentials (bad signature)
2. 401, time invalid authentication credentials (stale timestamp)
   • this response will also include the server's unix time in the header Server-Time
3. 401, not registered invalid authentication credentials (identityKey & deviceId not registered)
4. 401, badly formed credentials invalid authentication credentials (basic_auth username & password missing or malformed)
5. 401, revoked invalid authentication credentials (identityKey revoked)
6. 415 badly formatted request body.
7. 200 request succeeded. The body below is returned
8. 205 request succeeded. Must produce and upload more prekeys. The body below is returned.

{
    messagesQueued : 0,
    keysNotFound : [],
    revokedKeys : [],
    missingDevices : []
}

1. messagesQueued is the number of messages (a different message pre recipient/device) that have been successfully queued
2. keysNotFound is an array of recipients who's indentityKey was not found in the database. It contains 0 or more strings of the form <indentityKey>|<deviceId>.
3. revokedKeys is an array of recipients who's indentityKey has been revoked. It contains 0 or more strings of the form <indentityKey>|<deviceId>.
4. missingDevices is an array of recipients who's indentityKey does not contain the associated deviceId. It contains 0 or more strings of the form <indentityKey>|<deviceId>.

##Receiving a message See Push Socket Protocol wiki page.

basic_auth

#####username The username is of the form base64(identityKey)|deviceId where base64(identityKey) is your longterm public key base 64 encoded and deviceId is the device ID of the device you are making the request from. #####password The password is of the form timestamp|signature(timestamp)where timestamp is the current unix time and signature(timestamp) is a signature of the unix time from your longterm private key.