Initial Request¶

Authenticate your application when using the OnSite API by including the App ID and Private ID as well as the Lightspeed username and password in the header of the request.

There are three headers. The Private ID is included in the X-PAPPID header, the App ID is included in the User-Agent header, and the Lightspeed username and password are included in the Authorization header and uses HTTP Basic Auth.

# Request
#
# Headers:
#   X-PAPPID: {Private ID}
#   User-Agent: {App ID}/{App Version}
#   Authorization: Basic {base64 encoded username & password}
#
$ curl -k \
--header 'X-PAPPID: 12345678-90ab-cdef-1234-567890abcdef' \
--header 'User-Agent: com.lightspeed.onsite.demo/1.0' \
--header 'Authorization: Basic bGlnaHRzcGVlZDphZG1pbg==' \
--request GET 'https://localhost:9630/api/'

# Response
<resources/>

Subsequent Requests¶

When you make the initial request, you are logged into the Server as the user specified in the Authorization header. This creates an active session that will stay open until we close it. To re-connect to the same session, you have to store the LS_SERVER_SESSION_ID cookie from the server and send it back with each subsequent request.

If we don’t do this, we end up with multiple sessions open with the same user that can only be closed by restarting the Server. In this example, the command will save cookies in ~/Library/Cookies/com.acme.app.cookies.

There is a maximum number of sessions for applications which is equal to the number of seats for read/write access. See Registering Your Application for information on access. There is no such maximum for applications with read access.

$ curl -k \
--header 'X-PAPPID: 12345678-90ab-cdef-1234-567890abcdef' \
--header 'User-Agent: com.lightspeed.onsite.demo/1.0' \
--header 'Authorization: Basic bGlnaHRzcGVlZDphZG1pbg==' \
--cookie-jar $HOME'/Library/Cookies/com.acme.app.cookies' \
--cookie $HOME'/Library/Cookies/com.acme.app.cookies' \
--request GET 'https://localhost:9630/api/'

Logging Out¶

Our session will persist until we send a POST request to the /api/sessions/current/logout/ endpoint.

$ curl -k \
--header 'X-PAPPID: 12345678-90ab-cdef-1234-567890abcdef' \
--header 'User-Agent: com.lightspeed.onsite.demo/1.0' \
--header 'Authorization: Basic bGlnaHRzcGVlZDphZG1pbg==' \
--cookie-jar $HOME'/Library/Cookies/com.acme.app.cookies' \
--cookie $HOME'/Library/Cookies/com.acme.app.cookies' \
--request POST 'https://localhost:9630/api/sessions/current/logout/'

Authentication with Python¶

With a bit more set-up, that first request can also be accomplished using a script. The language of choice in this example, and the tutorials, is Python. Before writing code, the project has to be setup. See the instructions in Sending Your First API Request.

Create the following authentication.py file. The file will contain the following:

"""
Update a customer using the OnSite API.
"""
import requests

# Customize these to your install.
ONSITE_HOST = 'localhost'
ONSITE_PORT = 9630
ONSITE_USERNAME = 'lightspeed'
ONSITE_PASSWORD = 'admin'
APP_ID = 'com.lightspeed.onsite.demo'
APP_VERSION = '1.0'
APP_PRIVATE_ID = '12345678-90ab-cdef-1234-567890abcdef'

# Create a session. This will persist cookies across all requests.
session = requests.Session()
session.auth = (ONSITE_USERNAME, ONSITE_PASSWORD)
session.headers.update({
    'user-agent': '%s/%s' % (APP_ID, APP_VERSION),
    'x-pappid': APP_PRIVATE_ID})
session.verify = False

# Get a list of products.
# This is the first request. It creates the session with the OnSite API.
get_products_request = session.get('https://%s:%d/api/products/' % (ONSITE_HOST, ONSITE_PORT))
assert get_products_request.status_code == 200

# Get a list of customers.
# Subsequent requests continue the session with the OnSite API.
# Behind the scenes, the LS_SERVER_SESSION_ID cookie is being passed around.
get_customers_request = session.get('https://%s:%d/api/customers/' % (ONSITE_HOST, ONSITE_PORT))
assert get_customers_request.status_code == 200

# Log out.
logout_request = session.post('https://%s:%d/api/sessions/current/logout/' % (ONSITE_HOST, ONSITE_PORT))
assert logout_request.status_code == 204

print("Created a session, retrieved customers & products, and logged out successfully.")

You can now execute the script from the terminal:

# Execute the code.
python authentication.py

# Output
Created a session, retrieved customers & products, and logged out successfully.

The example uses Request’s Session, which utilizes connection pooling. If you’re making several requests to the same host, the underlying TCP connection will be reused, which can significantly increase performance. Consider utilizing a similar approach with your application should you use a different library.