Authentication

The Novant API uses API keys to authenticate requests. Each key is scoped to either a single project or an entire organization - see Project and Organization Keys. You can view and manage your API keys in the Novant Dashboard.

API keys are alphanumeric strings, which are prefixed with ak_ to help identify. Example code uses the sample key ak_sample_123. This key is non-functional and is used for demonstration purposes only. Replace the key with your own key for production.

Your API keys carry many privileges, so be sure to keep them secure! Do not share your secret API keys in publicly accessible areas such as GitHub, client-side code, etc.

Authentication to the API is performed via HTTP Basic Auth. Provide your API key as the basic auth username value. Use a empty string as your password.

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.

# The colon after API key prevents curl from asking for a password
curl https://api.novant.io/v1/project \
  -u ak_sample_123: \
  --compressed

Project and Organization Keys

There are two types of API keys:

Both key types use the same endpoints, and both are created with a mode that sets the key’s permissions.

Use a project key when an integration works with a single project. Use an organization key when an integration works across your portfolio.

Project Keys

A project key is bound to the project it was created in, so requests do not need to identify a project.

Project keys may optionally include proj_id, which allows an integration to send proj_id regardless of key type. If supplied, it must match the key’s project.

Organization Keys

An organization key can access every project in the organization, including projects added after the key was created. Only organization admins can create organization keys.

Because an organization key can reach many projects, every request to a project endpoint must include proj_id to name the project to act on. A request is never applied to a default project.

# Organization keys must name the project with proj_id
curl -G https://api.novant.io/v1/zones \
  -u ak_org_sample_123: \
  -d proj_id=4821 \
  --compressed

Use Organization Projects to list the projects an organization key can access, along with their proj_id values.

Each request made with an organization key is recorded in the API log of the project it accesses, and counts toward that project’s monthly data usage.

Anyone with an organization key can access data from every project in your organization. Keep organization keys private, share them only with integrations you trust, and revoke them immediately if they may have been exposed.

Permissions

Every key is created with a mode that sets its permissions. Each mode includes everything the modes above it can do:

A request to an endpoint the key’s mode does not allow is rejected with 403. See API Keys for help choosing a mode.

Key Errors