Presence V3 API (3.0.0)

POST /disconnect

This endpoint forces a signed in user to leave any room they are in and "disconnect" from presence.

GET /invites:

If a user has been invited to a room, then this endpoint will return that invitation's data. This invitation will be in a list and will contain the information about the room and who invited them. A list may contain more than one roomInvitation.

On the frontend, the user will be able to view these invitations as cards at the top of the dashboard. These cards will allow the user to accept the invitation & join the invited room. If a user does not have any pending invitations, then this view will not show.

POST /invites

If a user is in a room, they may send an email invitation to another user. This endpoint will pre-approve a different user for the room and send them an email invitation with a link to the room. This means that they will not require approval before joining the room and will be able to immediately join the room.

The other user will receive an email that contains a URL to the invited room. The user will also know that they have been invited to the room when they go to the SME Connect dashboard. The get request of the invites endpoint will retrieve their pending room invitations.

GET /jwt

This endpoint is called when a user enter a room. jwt provides the user with a JSON Web Token that will be used to log the user into the assets service. This will grant them privileges in viewing and annotating documents/image/CAD models.

Each JWT is specific to the individual room that the user is in.

GET /login

The login process occurs once a user has a valid JWT token provided by the auth service. When a user logs into SME Connect, the presence login endpoint will create a valid service session and return a session cookie to the user. This cookie is valid for a 2 hour window. The session cookie stores the user's credentials, which will provide authorization for interacting with the different presence services, such as joining and creating rooms.

When a user logs into presence for the first time, the user will have a new User record created. This record will originally contain just their name, uid (email), and uuid (unique ID).

GET /logout

The logout endpoint is called when a user selects to log out of SME Connect through the frontend. This endpoint will expire the user's cookie and end their current session. A 200 response indicates success.

GET /negotiate

This endpoint will negotiate a user's connection to Web PubSub. It will confirm a user has an existing session, and if valid, will return connection details on how to connect with Web PubSub. This endpoint will provide the endpoint for the Web PubSub and a JWT for accessing it.

POST /otp/send

The endpoint is called when a user requests to log into SME Connect with just an email. A hashed version of an OTP is stored in the presence DB along with the salt and user's email. This data will be used in the validate endpoint (otp/validate). Users will receive an email notifying them of their OTP. This 8-digit passcode will have a 15-minute window to use and validate.

Users that log in with just an email may experience restrictions with their account. These restrictions are intentional as specific login methods, such as CAC, are the authorized ways of logging in.

POST /otp/validate

This endpoint validates an OTP that a user submits. The OTP should have been generated first by /otp/send and retrieved from an email that contained the valid OTP.

This endpoint will validate the OTP that the user provides by checking the user-submitted OTP with the stored hashed version found in the presence DB. If the OTP matches what is stored in the DB, then the endpoint will return a valid JWT token for js_common to then use to send to the authn endpoint. This will ultimately allow the user to log into all SME Connect services having used just their email.

NOTE: Users will experience restrictions to their account when signing in with just their email and an OTP. Restrictions will include not being able to create a room.

POST /rooms/approve/{uuid:guid}

In the flow of SME Connect, this endpoint will occur once a user has requested to join a room. If they have not been previously approved for the room, then two SOCKET.IO events will be triggered. This first will be to notify users already in the room that someone has requested to join. The 2nd will be to send the requesting user to wait until they are approved.

Users in the room will see a "Approve" button notifying them of a user requesting to join the room. If a user clicks Approve, then this endpoint will be called.

This endpoint will check that the user who is approving someone is currently in the requested room. Upon a successful completion of this endpoint, the following will have happened:

• The requesting user will have a new userRoom entry in the presence DB. This indicates that they are now approved for the room and do not need future approvals.
• A socket event will tell existing users that a new user joined the room. This will help establish WebRTC connections.
• The new user will be added to the socket room. (Note -- the Tools Gateway will not have a socketID and will not complete this step. This will prevent unnecessary socket connections to the Tools Gateway)

Notes about the approval process:

• Users may only approve users to join the room that they are currently in.
• This endpoint is how the Tools Gateway (EmbeddedNode) joins a room. A scanned QR code (or for developers, using the console) is what will call this endpoint for the Tools Gateway.

POST /rooms

An authorized user may create a room. An authorized user is determined by their email and method of login. For example, a user is authorized if they log in with their CAC card and email has some version of "@mil" in it. If a user is unauthorized, they will not be able to create a room.

This endpoint will achieve the following:

• Create a new room & add its data to the DB
• Approve the user to the room. This approval will be shown in the DB entry: userRoom

On the front-end, the user will be put in the waiting area where they can then join the room's session by clicking on the "Join Session" button.

GET /rooms

This endpoint will return a list of rooms that a user is approved to join. The rooms list will include any members who are currently in the room. If a user has not been approved for any room, then an empty array will be returned.

This request may include different parameters to narrow the list of approved rooms. For example, there may be a modified or created parameter included with this request. This will filter the results based on a specified timestamp.

GET /rooms/{uuid}

This endpoint will return a room's data, including a members list, based on the provided UUID. A members list will only be provided if the user has been previously approved for that room.

GET /rooms/{shortname}

This endpoint will return a room's data, including a members list, based on the provided shortname. A members list will only be provided if the user has been previously approved for that room.

GET /user

This endpoint returns a user's information. This endpoint will only return a user's own record and information. A user may not get another's information from this endpoint. This is determined by the user's session information.

DELETE /user

This endpoint will clear a user's approved rooms data. Once completed, a user will need to regain approval for any previously joined room. In the DB, the user's userRoom items will be removed.

This endpoint will create/update a new user in the DB. The data from this new record will be returned in the response.

This endpoint will update a user record in the DB. The serialized user data will be returned.

This endpoint returns a user's information based on the provided UUID. This endpoint will only return the requested user if the requesting user is of type "Tool". This endpoint is needed so that a "Tool" may now what room the Tools Gateway (EmbeddedNode) is in. If a user of any other type calls this endpoint, that user will only receive their own information.