Novant

Documentation

Search /
Sign in

API Keys

API keys let integrations and your own code access project data through the Novant API. There are two types of key, and choosing the right one is the main decision.

Choosing a Key Type

Key Type Prefix Access Created From
Project ak_ A single project Project Settings → API Keys
Organization ak_org_ Every project in the organization Organization Settings → API Keys

Use a project key when an integration works with a single project. This is the right choice for most integrations, and integrations that connect to one project at a time, such as Grafana, require one.

Use an organization key when an integration works across your portfolio, such as analytics or reporting that spans many buildings. An organization key can access every project in the organization, including projects added after the key was created, so treat it with more care than a project key.

Readonly vs Read/Write

Every key is created as either Readonly or Read/Write. Readonly keys can read data, but can’t write point values, import data, or start Explorer scans. Choose Readonly unless the integration needs to write back to your building systems.

Create a Project Key

Creating a project key requires the Manager role on the project.

  1. Open the project and select the Settings tab.
  2. Choose API Keys from the settings menu.
  3. Click Add.
  4. Choose a Mode — Readonly or Read/Write.
  5. Add Notes describing what the key is for and who it’s shared with.
  6. Click Add.

The new key appears in the list. Use the copy button next to the key to copy it to your clipboard, or the eye button to reveal it.

Create an Organization Key

Creating an organization key requires the Admin role in the organization.

  1. Open your organization and choose Settings from the organization sidebar.
  2. Choose API Keys from the settings menu.
  3. Click Add.
  4. Choose a Mode — Readonly or Read/Write.
  5. Add Notes describing what the key is for and who it’s shared with.
  6. Click Add.

Anyone with an organization key can access data from every project in your organization. Share organization keys only with integrations you trust.

Integrations using an organization key must name the project on each request. See API Authentication for details.

Edit and Revoke Keys

To update a key’s notes, select the key and click Edit, or right-click the key and choose Edit Notes.

To revoke a key, select the key and click Revoke, then type REVOKE to confirm. Revoking takes effect immediately — any integration using the key loses access — and can’t be undone.

Monitor API Usage

Every API request is recorded in the API Log of the project it accesses, including requests made with organization keys. Open it from the project’s Settings tab, under API Log.

Each entry shows the time, the request, the key that made it, and the client’s user agent. Keys are shown masked — for example ak_org_abcxxx — so you can tell which key made a request without exposing it.

Keeping Keys Secure