Skip to main content

Getting Started

Poly Lens APIs Overview​

The Poly Lens Management and Insights API (Poly Lens API) provides access to the same rich operational data and management controls used within the Poly Lens cloud. With access to these APIs, you can build applications to manage accounts, device inventory, device configuration, gather insights, and much more.

The Poly Lens Management and Insight APIs (Poly Lens APIs) are implemented using the GraphQL query language. A major advantage of GraphQL is the ability to retrieve the data you need in a single HTTP request, improving efficiency and minimizing over/under fetching. GraphQL supports many languages, enabling integration with native and web applications, CLI scripts, and API tools like Postman.

Authentication and Authorization​

Before getting started, you must create an API Connection in your Poly Lens Account (Tenant). This process generates a set of API Credentials (client_id & client_secret). When developing outside the Poly Lens API Playground, you'll exchange the API Credentials for an access_token.

Create an API Connection in the Poly Lens Cloud​

  1. Log in to the Poly Lens cloud.
  2. Go to the ACCOUNT menu > Manage Accounts.
  3. Select an Account from the list.
  4. Select Integrations > API from the side tab.
  5. Select Create API Connection.
  6. Enter a Name and Role and select Confirm.
    The new connection displays in the API Connection List.

Edit an API Connection​

  1. Go to the ACCOUNT menu > Manage Accounts.
  2. Select an Account from the list.
  3. Select Integrations > API from the side tab.
  4. Select an API connection from the list (this enables the Edit button).
  5. Select Edit.
  6. Edit the connection as needed and select Confirm.

Delete an API Connection​

  1. Go to the ACCOUNT menu > Manage Accounts.
  2. Select an Account from the list.
  3. Select Integrations > API from the side tab.
  4. Select an API connection from the list (this enables the Delete button).
  5. Select Delete.
  6. Select Delete to confirm.
    The API Connection is deleted from the list.

Developer Tools: The API Playground​

The API Playground provides the opportunity to explore and test GraphQL queries against real data from Poly Lens Accounts (Tenants) for which you have access. It's designed to help you test, validate, and seamlessly integrate queries into your codebase.

API Playground Access​

Access to the API Playground requires authentication using your Poly Lens credentials. By default, API data access is scoped to your authenticated user. If your user has access to multiple Poly Lens tenants via the Poly Lens user interface, the same applies in the API Playground. For queries that don't require a tenantId parameter, responses will include data from all tenants your user is authorized to access.

To narrow the API data scope to a single Account (Tenant), we've displayed an option to use Client Credentials. To use a set of credentials, at the top of the API Playground, toggle Use Client Credentials on and select the credential name to use from the dropdown list.

Poly GraphQL Client Credentials Option

The API Playground is divided into three main sections:

  • Left: The Schema, which shows all available Root Types (query, mutation, and subscription). Selecting a Root Type displays all available Fields. Select a Field to see the Arguments, Fields, and Types for the object.
  • Middle: Where you'll write GraphQL Queries, add variables, and run the operation.
  • Right: Displays the Response Object, the HTTP Response Status, and the option to display the response as JSON or in a table.

Poly GraphQL Playground main page after authenticating

Efficient Querying with Pagination​

Some queries, like deviceSearch, can return large and deeply nested responses due to the number of fields and subfields involved. This increases the processing load on the server and can slow down response times. As a best practice, always request only the data you need. When constructing large or complex queries, implementing pagination helps improve performance by reducing payload size and server processing load, resulting in faster response times and a lower risk of throttling.

Queries that support pagination include a pageInfo object, which provides four metadata fields:

  • totalCount: The total number of results
  • countOnPage: The number of results returned in the response
  • nextToken: The token to retrieve the next page
  • hasNextPage: True if there are more results available

To use pagination:

  1. Add the pageInfo fields to your query.
  2. Add nextToken: null to the parameters of the initial query.
  3. Run the query. If hasNextPage: true, then nextToken will contain a value.
  4. Pass the nextToken value into the parameters of the next query.
  5. Run the query again and you'll get the next batch of results. Repeat this process until hasNextPage: false and/or nextToken: null.

Pagination steps one through three Pagination steps four through five

Developing Applications and Obtaining Credentials​

There are two URLs you'll use when integrating Poly Lens APIs into your applications.

Exchange API Credentials for an access_token​

The Poly Lens API GraphQL endpoint requires an Authorization header with a valid bearer token: Authorization: Bearer <access_token>. The access_token is a digitally signed string (JWT) that describes what API access you've been granted. To obtain an access_token, run a POST request and exchange your Client ID and Client Secret.

If you're not wrapping this step into your code flow, you can use the pre-populated cURL request to copy and paste it into your API tool of choice.

Obtaining the Pre-Populated cURL Request

  1. Login to the Poly Lens cloud.
  2. Go to ACCOUNT menu > Manage Accounts.
  3. Select an Account from the list.
  4. Select API Credentials from the side tab.
  5. Select a Client ID from the list.
  6. This opens a popup with Sample Code.
  7. Copy this to your clipboard.

Poly Lens UI pre-populated cURL request

Generating an access_token

Paste the Sample Code into your API tool of choice. If you're using a CLI, it should look like this:

sample cURL Post Request

After sending the request, you should receive an HTTP 200 ok response containing the following:

sample cURL Post Response

info

Tokens expire in 24 hours.

Get Help​

If you have questions about usage, authentication, or integration with the Poly Lens APIs, contact us.