loginwith.me

This is the API documentation for loginwith.me which allows you to programmatically create sessions and executables to establish remote connections, send emails, get chat logs, and more.

Note that the terminology "presenter" as used throughout the documentation is referring to the software which runs on the PC and allows users to connect to the PC through the loginwith.me website. The term "viewer" refers to the webpage on the loginwith.me website which allows a user to both view and take control of the presenter's screen. Also note that there can be multiple viewers per remote session, but only one presenter.

This API is permitted for for use by individuals for PERSONAL USE and business for INTERNAL USE. If you wish to sell or otherwise distribute a product which makes use of this API, you you must have a signed licenses agreement by Tier2 Technologies.

Obtaining such a licenses agreement is easy and inexpensive; or in some cases free. Email support@tier2.tech for more info.

GETregions

https://www.loginwith.me/api/v1/regions

The first step of establishing a remote session is to decide which region you want to allocate the session in. This is important because remote-support is a latency-sensitive activity, so you want the session-host to be as low-latency as possible. That generally means that you want to pick a region as physically close to you as possible.

This example shows how to query for the available regions, but to automatically determine which region among these is the best choice, you must perform a latency test on each region by querying a subdomain on the loginwith.me site which is named the same as the region: https://{region}.loginwith.me

For example, to test the latency of "us-east-1" you would perform an HTTP GET on us-east-1.loginwith.me and you would time the milliseconds it takes to respond.

Repeat this process for each region returned in the /regions query and choose the region with the lowest response time. (Note that it's best the perform the test multiple times on each region and pick the best of all results because things other than network latency can contribute to the response time -- such as server-load)

Since doing this is a non-trivial development exercise, we have published a JavaScript library which will do the heavy-lifting for you: https://www.loginwith.me/resources/latency_test.js

We also have an example of how to use the library: https://www.loginwith.me/resources/latency_example.html

Example Request

curl

curl --location 'https://www.loginwith.me/api/v1/regions'

200 OK

Example Response

json

[
  "ap-southeast-2",
  "us-east-1",
  "us-west-2",
  "eu-west-2",
  "ca-central-1"
]

Date

Wed, 04 Aug 2021 22:55:48 GMT

Content-Type

application/json; charset=utf-8

Transfer-Encoding

chunked

Connection

keep-alive

Content-Security-Policy

default-src 'none'; frame-ancestors 'self'; base-uri 'self'; form-action 'self'; child-src 'self'; connect-src *.loginwith.me *.tier2.tech; font-src 'self'; frame-src 'self'; img-src 'self'; manifest-src 'self'; media-src 'self'; object-src 'self'; prefetch-src 'self'; script-src 'self'; script-src-elem 'self'; script-src-attr 'self'; style-src 'self'; style-src-elem 'self'; style-src-attr 'self'; worker-src 'self';

Strict-Transport-Security

max-age=15768000; includeSubDomains; preload

X-Frame-Options

SAMEORIGIN

X-Content-Type-Options

nosniff

Referrer-Policy

same-origin

Permissions-Policy

geolocation=(self), camera=(self), fullscreen=(self), microphone=()

Cache-Control

no-cache, no-store, must-revalidate

Expires

Access-Control-Allow-Origin

CF-Cache-Status

DYNAMIC

Expect-CT

max-age=604800, report-uri="https://report-uri.cloudflare.com/cdn-cgi/beacon/expect-ct"

Report-To

{"endpoints":[{"url":"https:\/\/a.nel.cloudflare.com\/report\/v3?s=GXBWTQotMD5Nit%2FFhNLbDGk%2BRaKuKLBuQ%2Bxnmx9yz7zHm4vXjrHLghDI6pvA19tz0iZNNcvlLJd2bQIJk2h6HdKXckBCGzzblz9kMQS0hBC2cQeuy9H5p89%2B7FXBhGPzR9i%2F"}],"group":"cf-nel","max_age":604800}

NEL

{"success_fraction":0,"report_to":"cf-nel","max_age":604800}

Server

cloudflare

CF-RAY

679b60168b2e1084-ATL

Content-Encoding

alt-svc

h3-27=":443"; ma=86400, h3-28=":443"; ma=86400, h3-29=":443"; ma=86400, h3=":443"; ma=86400

GETsession_pin

https://www.loginwith.me/api/v1/session_pin?region=us-east-1

After you have determined which region will best suite your needs by querying /regions, and performing a latency test, it's time to allocate a session within that region. Once the session is allocated, you will receive a "Session PIN" which is used to authenticate both the presenter and the viewer, and is important to keep private while the session is in progress. Anyone with the Session PIN can have access to the presenter's PC, so treat it with care.

PARAMS

region

us-east-1

Example Request

curl

curl --location 'https://www.loginwith.me/api/v1/session_pin?region=us-east-1'

200 OK

Example Response

json

{
  "success": true,
  "session_pin": "7W2-97-8570"
}

Date

Wed, 04 Aug 2021 22:55:56 GMT

Server

Apache/2.4.41 (Ubuntu)

Content-Security-Policy

default-src 'none'; frame-ancestors 'self'; base-uri 'self'; form-action 'self'; child-src 'self'; connect-src 'self'; font-src 'self'; frame-src 'self'; img-src 'self'; manifest-src 'self'; media-src 'self'; object-src 'self'; prefetch-src 'self'; script-src 'self'; script-src-elem 'self'; script-src-attr 'self'; style-src 'self'; style-src-elem 'self'; style-src-attr 'self'; worker-src 'self';

Strict-Transport-Security

max-age=15768000; includeSubDomains; preload

X-Frame-Options

SAMEORIGIN

X-Content-Type-Options

nosniff

Referrer-Policy

same-origin

Permissions-Policy

geolocation=(self), camera=(self), fullscreen=(self), microphone=()

Cache-Control

no-cache, no-store, must-revalidate

Expires

Access-Control-Allow-Origin

Content-Length

Keep-Alive

timeout=5, max=99

Connection

Keep-Alive

Content-Type

application/json; charset=utf-8

PUThook

https://www.loginwith.me/api/v1/hook/

This API endpoint can be used to create webhooks for a given session. When a webhook is created for a given URL, that URL will receive a JSON POST from the loginwith.me session broker when certain events occur -- along with with information about the event.

There are currently four types of events that are supported:

viewer_started

This webhook is fired when a browser viewer is started (when a web browser navigates to the URL provided by the /session_url query). Note that loginwith.me supports multiple viewers on each session, and a viewer may end and then restart (such as if the page is refreshed), so this event can be made to fire multiple times throughout a session.

Note that the output from this event is compatible with the input for the /email API endpoint, and can therefore be used to notify a presenter (by email) that a viewer is waiting for them as soon as the viewer connects.

presenter_started

This webhook is fired when a presenter executable is in a state in which a viewer can now connect and view the screen. (when the user has run the program). Note that the exe could be clicked several times by the user, which would cause the app to restart each time; and so this event could be made to fire multiple times.

Note that the output from this event is compatible with the input for the /email API endpoint, and can therefore be used to notify a viewer (by email) that a presenter is waiting for them as soon as the presenter connects.

presenter_offline

This webhook is fired when a presenter which had been online in the past (and submitted a presenter_started hook) is no longer online. This could be because the session was purposely ended, or from a network outage, computer crash, etc. Note that this will only fire after the presenter has been offline for > 60 seconds to prevent false notification from presenters restarting to elevate to admin, or from short network-blips.

viewer_offline

This webhook is fired when a viweer which had been online in the past (and submitted a viewer_started hook) is no longer online. This could be because the session was purposely ended, or from a network outage, closed browser window, etc. Note that this will only fire after the viewer has been offline for > 60 seconds to prevent false notification from viewers restarting from refreshing the page, or from short network-blips. Also note that loginwith.me supports multiple viewers for a single presenter, and this will only fire 60 seconds after all viewers are offline.

caveats

Note that only four hooks can be set per-session at any given time. Calling the endpoint again will only edit a hook URL for a given type, not create an additional hook. If you need a single event to post a webhook to multiple URL's then you must design an external webhook relay, which can accept the single hook and then forward that request to your desired other URLs

Note that once a hook fires, it has been "consumed" and will not by default fire a second time, even if the same event occurs again. It can, however, be made to fire again on subsequent events by having the receiver call this same API endpoint again with the same parameters to "re-set" the hook each time it is consumed.

Bodyraw (json)

json

{
    "type": "viewer_started",
    "url": "https://www.loginwith.me/api/v1/email/loginwithme@example.com",
    "session_pin": "7W2-97-8570"
}

Example Request

curl

curl --location --request PUT 'https://www.loginwith.me/api/v1/hook/' \
--data-raw '{
    "type": "viewer_started",
    "url": "https://www.loginwith.me/api/v1/email/loginwithme@example.com",
    "session_pin": "7W2-97-8570"
}'

200 OK

Example Response

json

{
  "success": true
}

Date

Wed, 04 Aug 2021 22:56:13 GMT

Server

Apache/2.4.41 (Ubuntu)

Content-Security-Policy

Strict-Transport-Security

max-age=15768000; includeSubDomains; preload

X-Frame-Options

SAMEORIGIN

X-Content-Type-Options

nosniff

Referrer-Policy

same-origin

Permissions-Policy

geolocation=(self), camera=(self), fullscreen=(self), microphone=()

Cache-Control

no-cache, no-store, must-revalidate

Expires

Access-Control-Allow-Origin

Content-Length

Keep-Alive

timeout=5, max=99

Connection

Keep-Alive

Content-Type

application/json; charset=utf-8