Fautore API: osaInvite
Send an invitation to connect with an external POD/OCE.
Table of contents
Overview
This page details the operation and use of the "osaInvite" function. The invite process assumes personal interaction before an invite can be extended. The inviting OCE must first be supplied with the address, port and password of the OCE being invited before the invitation can be extended. The workflow being supported is that of one person passing another person the OCE credentials so the receiving party can then extend an inviation to connnect POD environments and begin communications. Think of it as the equivelant of giving someone your phone number and saying, "call me sometime."
Automated registration with online companies could be achieved by the company developing a data entry form to which the site visitor would enter the address, port and password for receiving the invite. The company site would then automatically send an invitation to the site visitor to partake in whatever services or marketing campaigns motivating the request to participate.
Invitation Structure
The OCE connection invitation data structure is constructed of encoded JSON passed within the "Adjunct":"Data" portion of the master OSA message being used to pass the data to the OCE.
Function: osaInvite
Source:
The inviting tribe member manually enters credentials provided by the party being invited. The local OCE populates the invitation with specifics for the remote OCE to establish a return connection.
Example:
This is a decoded JSON invitation data structure. Note that the "Adjunct=>Data" field is JSON text being carried as data within the data structure. In a live program the "Adjunct=>Data" field would be JSON decoded into its own data structure.
Full Messge Example
$Invite = { 'msgType' => 'oceOp', 'Private' => '2', 'Summary' => 'Example osaInvite data structure' 'Detail' => 'This is an example osaInvite data structure showing the API call in the "Adjunct=>Data field", 'Source' => { 'Member' => 'Bonnie', 'Key' => '41B13D17D51E24A95B13D17D51E24A95B13D17D51E24A95B13D17D51E24A95B1', 'Coterie' => '1' }, 'Adjunct' => { 'Desc' => 'An example osaInvite API call', 'Data' => '{ "Func" : "osaInvite", "InviteKey" : "54989C1A17189A9A97191A9817189A2D22253EA016AA9F221720161E80A84F18A71A41E80A84F18A71A41E80A84F18A71A41E80A84F18A71A41E80A84F18A71A", "InvitePass" : "SpeakFriendAndEnter", "Computer" : "192.168.42.117", "Port" : 1895, "PodName" : "TekAdvocates" "PodDesc" : "The OCE of the Technology Advocates", "PodManager" : "TekAdvocates", "PodMgrContact" : "Info@TekAdvocates.com" "ReqMembers" : [ { "Login" : "Todd", "fName" : "Todd", "lName" : "Pratkinson", "Pass" : "jest3ME1#&HW", "Email" : "Todd@SomeEmail.org", "About" : "Hard working little brother" }, { "Login" : "Bonnie", "fName" : "Bonnie", "lName" : "Grotsenburger", "Pass" : "G#AJE*64lq82GD", "Email" : "Bonnie@SomeEmail.org", "About" : "Sweetie pie" } ] }' }, };
Field Definitions
The below table defines each data value of the osaInvite API call itself, as stored in the "Adjunct=>Data" field. Refer to the USDS page for an explanation of the complete message structure.
- Func
- Required,Keyword - Name of API function being called
- InviteKey
- Required,128 character string (64 hex digit) key used to establish initial invitation encryption. Long term keys are exchanged within the encrypted session.
- InvitePass
- Required,Unlimited - Pass key provided through real world interaction by the OCE manager being invited. This pass key is used for identification purposes and not stored.
- Computer
- Required, 64 character sting - Computer reference (IP or FQDN) provided through real world interaction by the OCE manager being invited.
;Port|Optional, 5 digit integer - Computer port reference provided through real world interaction by the OCE manager being invited. Defaults to 1895.
- PodName
- Required, 60 character string - Human readable identifier for inviting POD.
- PodDesc
- Required, Unlimited - Human readable description for the inviting POD
- PodManager
- Required, 60 character string - Human readable reference to person or company responsible for the inviting OCE
- PodMgrContact
- Required, 254 character - Contact information for the listed POD manager, usually an email address
- ReqMembers
- Optional, array - List of inviting tribe members being requested for addition as remote members to the OCE being invited to register.
| SubField | Disp | Type | Description |
|---|---|---|---|
| Login | req | string(45) | Requested login Id in remote OCE. Login to remote OCE is optionally enabled. This identifier is used primarily to recognize message senders. |
| fName | req | string(45) | First name of requested OCE member |
| lName | req | string(45) | Last name of requested OCE member |
| Pass | req | string(64) | Requested password for requested OCE member |
| opt | string(254) | Email contact for requested OCE member | |
| About | opt | text | Descriptive text for requested OCE member |
Returns:
The response returned is a 2 field JSON structure:
MsgId:
- Positive numbers indicate success
- Negative numbers indicate rejection
- NULL = Request failure, programmatic error
Mesg:
- Descriptive text explaining the MsgId
Upon Success:
- MsgId = 1
- Mesg = Fautore id for the application reference
Upon Rejection:
- MsgId = negative reason code (table of codes TBD)
- Mesg = Text of message describing reason for rejection (i.e. Application already registered for user.)
Upon Failure:
- undef
Data Mapping
Data accepted by the osaInvite function stores it's data as indicated in the below table.
Main
Data mapping for primary invite data
| JSON | Table | Field | Comments |
|---|---|---|---|
| InviteKey | Tribe | TribeKey | Initial encryption key |
| InvitePass | N/A | N/A | Programmatic value not stored |
| Computer | Tribe | IP | network identifier for inviting computer (IP or FQDN) |
| Port | Tribe | Port | Comms port on inviting computer (defaults to 1895) |
| PodName | Tribe | TribeName | Human readable name for the inviting POD |
| PodDesc | Tribe | Description | Textual description of inviting POD |
| PodManager | Tribe | Owner | Individual or company maintaining the POD OCE |
| PodMgrContact | Tribe | Contact information for the inviting POD. Fautore assumes it to be email, that is not however required by the spec. |
ReqMembers
Data mapping for requested member data
| JSON | Table | Field | Comments |
|---|---|---|---|
| Login | User | UserName | Remote member login |
| fName | User | fName | Remote member first name |
| lName | User | lName | Remote member last name |
| Pass | User | Password | Password for use loging in to remote OCE, if account is enabled for login. |
| User | Email address for requested member. | ||
| About | User | About | Textual description of remote member. |
Workflows
The below workflow describes the process for an OCE-toOCE invitation interaction. (One OCE inviting the other to connect)
Personal Invitation
"Invitation" is the process of one OCE inviting another to connect so that messages can be exchanged.
- A real world meeting of two people occurs (Tome and Mary)
- Tom says he'd like to stay in touch with Mary and she hands him a preprinted card with her OCE FQDN and port listed on the front. Mary has handwritten the current password for Tom to extend an invite to her OCE on the back of the card.
- Tom enters the FQDN, port (if other than 1895) and invite password to his OCE.
- Tom's OCE sends an osaInvite to Mary's OCE.
- Mary's OCE receive's the invite and validates the password received in the invite is correct.
- An encrypted connection is set up using the passed InviteKey.
- Tom's POD information is stored to Mary's OCE
- Mary's OCE acknowledges receipt by passing a success MsgId (1) and a new POD key in the Mesg value.
- Tom's OCE creates a new POD key merge's it with Mary's recently returned POD key and stores it as the relationship comms encryption key.
- Tom's OCE send Mary's OCE an osaNewKey API call with the key his OCE created by merging with Mary's returned key.
- Mary's OCE stores the passed key as being associated with Tom's OCE and return a success MsgId (1) and "Message received" type text "Mesg" value
Complete to This Point
Corporate Invitation
This needs to be finished.