> For the complete documentation index, see [llms.txt](https://help.highlight.net/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.highlight.net/functionality/provisioning-api.md). # Provisioning API ## Overview External APIs are a vital element of a Software-as-a-Service product. Highlight's Provisioning Application Programming Interface enables you to automate your service delivery. Our Provisioning API is initially focused on the creation of and updates to bearer watches. Future releases may include user management, working with other watch types, and interacting with other features like reporting, alerting, containers, and service tiles. [Contact us](https://help.highlight.net/getting-started/contact-us) for assistance acquiring and using the API. ## Description The Highlight API allows you to interact with your Highlight service programmatically from your organisation's service layer or applications. This release of the API provides facilities to add a new device to be monitored in Highlight (a "watch"), search for a watch, and update its properties. Some common use cases for the API include: * Reconcile a device in your estate against Highlight, allowing you to find the corresponding watch if it has previously been added to Highlight * Query the current configuration of a device watch * Update a device watch, for instance changing the IP address, bandwidth, or interface information * Create a new watch for a circuit or device recently added to your estate The production API environment provides the following safeguards: * In Highlight's multi-tenant environment, each access key provides access only to the client's own data, at a customer or partner level, ensuring data privacy * Throttling of API requests to ensure that other users on the platform are not adversely affected by large-scale API activity * Logging of API activity to allow Highlight operational and development staff to understand usage of the API, providing information to support further development of the API. ## Authentication The Provisioning API authentication leverages Highlight as an identity provider, so that the credentials you use to login to Highlight will also work with the API. An endpoint is provided to allow you to use these Highlight credentials to obtain an access token to be used with future requests. All changes to Highlight using this token will be made on behalf of the user whose credentials were used to obtain it and logged against that user. There are a few caveats: * The user account used needs to have certain permissions set to allow the creation of folders, location, watches, and staging (Manage folders/locations, Edit watches, etc.) * The API feature also must be enabled for your organisation ## Resources The Provisioning API provides a REST interface for accessing watch records. Each watch is accessed via the API using its own unique ID. Once acquired, this ID should be added to your system with the information describing that device. Using this ID when calling the API in future allows fast access to these Highlight resources from your system when querying or updating the watch information using the API. ## Response and Request Data ### Response Data A watch's data is returned as a JSON object (formatted text that is human readable and readily understood). ### Request Data JSON objects are used to update and create watches. Searches and requests for a watch's details are a little more straight forward and only require a URL Refer to the API technical document for more details of these objects and how to use them. ## API Technical documentation See the PDF document for technical documentation. * **Provisioning API Technical Documentation** **Download PDF** ## API versions / compatibility The Provisioning API will work with your current version of Highlight. New versions of our API and any deprecation of our API features will be managed in a controlled manner to ensure sufficient time to update and/or change any integration code as required. ## Related * **User permissions** * [Contact us](https://help.highlight.net/getting-started/contact-us) --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://help.highlight.net/functionality/provisioning-api.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.