Experience Endpoints

An Experience Endpoint is a combination of an HTTP method and a route that, when invoked by an HTTP request, can fire a workflow. That workflow should then generate and issue a response to the request.

Viewing Experience Endpoints

Experience Endpoints

Endpoints are listed within the "Endpoints" tab of your application's "Experience" subsection. There is also a list of endpoints on the Experience overview page, sorted by most times invoked in the last 24 hours.

Click an endpoint's route in the list to view its configuration, make edits or view workflows associated with the endpoint.

Adding an Experience Endpoint

From the Endpoints list page, click "Add Endpoint" in the top right corner. This will take you to a page where the new endpoint can be configured.

Add Endpoint

Endpoint Configuration

Configuring an endpoint takes a few required fields, each of which has its own unique properties.


This is the HTTP method the request should match. It is possible to have one route handle multiple HTTP methods, but each method must be configured as a separate endpoint. Currently, we support these methods:

  • GET requests are typically used for retrieving existing resources. A GET request should be repeatable without changing the state of your application and should return the same response body across requests, assuming the underlying data does not change between requests.
  • POST requests allow for a payload to be sent with the request body. Though POST requests are typically used for creating new resources, they can also be used for complex data queries that require more configuration than can be conveyed in route parameters.
  • PUT requests also allow for a payload body; these requests are typically used to overwrite an existing resource.
  • PATCH requests also allow for a payload body; these requests are typically used to merge changes into an existing resource.
  • DELETE requests should only be used to delete resources from your application.
  • OPTIONS requests are typically sent by web browsers prior to making a cross-origin request. If you have the "Enable Default CORS Settings" box checked in your Experience Settings, it should not be necessary to set up any OPTIONS endpoints. However, you may still create your own OPTIONS routes, and any requests matching those routes will override the default settings handled by Losant.

Endpoint Method and Route


The route is the URL path, or the part after your Experience's domain. If your Experience's domain is https://my-custom-slug.onlosant.com, the route is the part that comes after the .com. It always starts with a slash / and may contain a series of static and parameter segments separated by more slashes.

There are a number of rules to consider when building your routes:

  • A single route may only be used once per method. However, a route of /my-route can be set up with a GET method for one endpoint and a POST method for another endpoint, and both are valid.
  • Routes are matched by order of specificity. The more specific a route, the earlier in the process it is checked when a request comes in. The first route that matches the path in the HTTP request will be invoked. Losant takes care of ordering the routes by specificity for you, based on the rules outlined here.
  • Routes can contain string literals, path parameters and wildcards. For example, given the route /devices/{deviceId}/{attribute?} ...
    • devices is a string literal, which is a static route parameter. String literals always take priority over the other parts of a route, meaning /users/danny will match before /users/{name} if "danny" is included in the name spot.
    • {deviceId} is a required path parameter. If a request is made to /devices/ without a {deviceId} after the trailing slash, the request will fail (unless you have also specified a /devices route matching that method).
    • {attribute?} is an optional path parameter; a request to /devices/123 and /devices/123/temp will both succeed and will both invoke the same endpoint, but the latter will include {"attribute": "temp"} as part of the payload passed to your workflow.
  • Routes must not conflict with each other. The most common example of routes conflicting is with the use of path parameters at the same priority level; for example, a route of /{deviceId} and /{userId} will conflict because, behind the scenes, the router does not know if the value in that part of the path is a device ID or a user ID. For this reason, it is a good idea to start your routes with a descriptive string literal, such as /devices/{deviceId} and /users/{userId}. If you attempt to create a route that conflicts with another route, you will be alerted of the error.
  • Routes can contain wildcards. Wildcards must be used with care, as they will match any request. A typical use case for a wildcard is if you want to create your own OPTIONS endpoint, or a custom 404 Not Found HTTP response; in that case, you would configure a route of /{var*}, where var is available on the payload with the value of whatever the user entered after the first slash in their custom Experience domain.

Access Control

Endpoint access – the ability of a specific user to invoke an endpoint with an HTTP request – can be configured a few different ways ...

Endpoint Access Control

  • All public users means that anybody, regardless of if they have an Experience User account within your application, no matter if they are currently signed in to their account, can access the endpoint. Public endpoints can be used to allow the retrieval of nonsensitive data; they are also essential to allowing users to sign in to your Experience, as the authentication endpoint must be available to non-signed-in users.
  • Any authenticated user endpoints can be invoked by any of your Experience Users when they are signed in. Their authentication token must be included in the request.
  • Only users who are in the following groups... limits access to signed-in users who are a member of any one of the specified Experience Groups. This is useful for building routes that have special privileges (such as resource editing permissions or Experience administration) that you do not want to provide to your normal population of users. To add a group to the endpoint, select the radio button next to the label and begin typing one or more group names into the input. You may also create new groups directly from this interface. Simply type the name of a group that does not yet exist.

Other Properties

There are a couple additional properties to set on each endpoint:

Other Endpoint Props

  • Enabled: Whether this endpoint should accept HTTP requests and issue responses. If the endpoint is not enabled, Losant will automatically issue a response of 404 Not Found - {"error": "No endpoint found for route"}.
  • Description: A simple description of the endpoint. This is for internal use only; it will never be visible to Experience Users.

Endpoints and Workflows

Every endpoint is powered by a Losant workflow built by you. The workflow is initiated by an Endpoint Trigger node configured to match your endpoint's method and route. From there, you can use any nodes within the workflow editor to parse your user's request, issue a response using an Endpoint Reply node, and take auxiliary actions (such as sending data to a third party or issuing alerts via email or SMS).

Endpoint Workflow List

At the bottom of an endpoint's edit page is a list of all workflows that contain an Endpoint Trigger Node that matches that endpoint's method and route. If no such workflows exist, you have the option of creating a starter workflow, which will contain an Endpoint Trigger node, an Endpoint Reply node and a Debug node. This serves as a getting started template for configuring your new endpoint; you simply have to fill in the logic between the trigger and the reply.

Experience User Nodes

There are a number of nodes built specifically for working with your Experience Users. Using these nodes, you can ...

Using Endpoints

Endpoint Workflow

Using your endpoints is as simple as issuing HTTP requests. When a request is sent to your custom domain, the HTTP method and path are compared against your existing endpoints, and the first one that returns a match fires any workflows with an Endpoint Trigger node for that endpoint. If your workflow includes an Endpoint Reply node (and it most definitely should), that request will then receive a response as generated by your workflow.

Passing Authorization Tokens

Once you retrieve an authorization token for an Experience User, that token can be appended to any subsequent HTTP requests that require authorization one of three different ways:

  • A query parameter added to the URL (e.g. https://my-custom-slug.onlosant.com/my-user?authorization=[my-token])
  • An Authorization HTTP header with the value Bearer [my-token]
  • A Cookie HTTP header in the format of authorization=[my-token] (you can set a cookie in the user's browser when they authenticate)

Testing Endpoints

One of the more popular tools for issuing HTTP requests is curl. If you are familiar with curl, chances are you already know how to build requests and test your endpoints.


If a command line interface isn't your thing, one of the better (and free) HTTP request builders is Google Chrome's Postman. The application includes a GUI for building requests for any HTTP method, sending payload bodies, setting route parameters, defining headers, and everything else you need to test your endpoints.

Deleting Endpoints

An endpoint can be deleted by clicking the "Delete" icon next to any endpoint on the list page, or by clicking the "Delete" button in the footer of an endpoint's edit page. Deleting an endpoint will automatically remove it from any of its Experience Groups.

Delete Endpoint

When deleting an endpoint, you also have the option of deleting any workflows triggered by that endpoint. Note that this action deletes any workflow with an Endpoint Trigger node matching this endpoint. If you wish to save your workflows and change out their triggers, or if the workflows are triggered by multiple conditions and you wish to retain them, you should leave this option unchecked.