openmsg.io
Initial Handshake
See also: Handshake: Guide
Good to know
'openmsg_address'
string
Max 255 character string. A string representing the User's Openmsg Address and unique to the User. Starting with digits, ending with a domain, and separated by a star "*". The first part is the openmsg_address_id, and the last part is the Receiving Nodes domain name.
Example: 123456789*openmsg.io
'openmsg_address_id'
string
This is the actual ID of the User. It is unique to each domain. Each Receiving Node can set their own limit on the length of this ID, as long as the maximum length of the openmsg_address is within limits
'openmsg_address_domain'
string
This is the location of where the POST request will be sent. It should be the domain name of the Receiving Node (taken from the last part of the openmsg_address). See the "Guides" link above.
Request Authorization
Sending Component
Parameters
'receiving_openmsg_address_id'
string
Required. A string of numbers representing the User's account ID with the Receiving Node. Must be stored as a string as leading zeros may be present.
'pass_code'
string
Required. 6 character string. A string of 6 numbers.
One-use only. 1 hour lifespan. Should be deleted by the Receiving Node after use or after one hour has passed since creation.
'sending_openmsg_address_name'
string
Required. Max 40 character string. Letters and numbers only.
This is for the Receiving Node to save so the User can easily identify who the messages are from in the furture.
Example: Monsters Inc Customer Service
'sending_openmsg_address'
string
Required. Max 255 character string. This is the reply address that links to any future messages coming from this Sending Node. By providing a reply address, the Sending Node is confirming that authorization is recipricated using the same auth_code and ident_code (below).
'sending_allow_replies'
bool
Required. Indicates if the initiator of the handshake accepts replies.
'openmsg_version'
string
Required. Indicates which version of the Openmsg Protocol the server is using.
JSON
POST
POST
$other_openmsg_address_domain/openmsg/1/auth 
{
      "receiving_openmsg_address_id": receiving_openmsg_address_id,
      "pass_code": pass_code,
      "sending_openmsg_address": self_openmsg_address,
      "sending_openmsg_address_name": self_openmsg_address_name,    
      "sending_allow_replies": self_allow_replies,    
      "openmsg_version": "1.0",    
}
Receiving Component
Response
'success'
boolean
"TRUE"
'auth_code'
string
A cryptographically secure randomly generated 32 character string converted to hex.
Use bin2hex(random_bytes(32))
A private code used to create a hash and identify the sender of a message.
Example: 4cbee0f12e92030d88fda73b2db5e70933406853d058b57721fb886f22939cd0
'ident_code'
string
A cryptographically secure randomly generated 32 character string converted to hex.
Use bin2hex(random_bytes(32))
A code used to identify the sender of a message.
Example: 796c748d334190a157015259c446a08c665ddf2e15a3b01e23d4bb3d08b304be
'message_crypt_key'
string
A secure 256-bit (32-byte) key.
Use base64_encode(sodium_crypto_secretbox_keygen())
Used for encrypting messages
Example: O8OpMs+lUjLuiXohc+iFZ20n9AEmvf+gSmUk84j/hRA=
'other_openmsg_address_name'
string
Max 40 character string. Letters and numbers only.
This is for the Sending Node to save so the User can easily be identified in the furture.
Example: Jane Doe
'error_message'
string
255 character string.
'error'
boolean
"TRUE"
JSON
Response
Success 
{
      "success": TRUE,
      "auth_code": auth_code,
      "ident_code": ident_code,
      "message_crypt_key": message_crypt_key,
      "other_openmsg_address_name": self_openmsg_address_name
}
Failure 
{
      "error": TRUE,
      "error_message": error_message
}
Confirm Authorization
Receiving Component
Parameters
'other_openmsg_address'
string
Required.
'pass_code'
string
Required.
JSON
POST
POST
$other_openmsg_address_domain/openmsg/1/auth-confirm 
{
      "other_openmsg_address": self_openmsg_address,
      "pass_code": pass_code
}
Sending Component
Response
'success'
boolean
Bool.
'error_message'
string
255 character string.
'error'
boolean
Bool.
JSON
Response
Success 
{
      "success": TRUE
}
Failure 
{
      "error": TRUE,
      "error_message": error_message
}