API Keys

Overview

API Keys are a ideal method for Server to Server communication were the credentials can be kept secure and therefor can remain untimed. The ability to send a non challenged initial request for data provides a quicker response for data. API keys remain scoped as well so you can use API keys with most levels of authentication from Basic User up to Super User.

Key Format

The API Key itself will be autogenerated on create and will not change. The keys will all be 60 characters long and consist of 3 parts described in some detail below. An example key looks like "nsu_ylP7TGZvubv2x3eO5fbHrLaByniJelnL0FRbHYKnevTvqIfC5897f65c".

Prefix (4 characters) - The prefix will help with readability and identifying that this is a "ns" (netsapiens) apikey as well as identifying the scope level in use to help a developer with expected restrictions.
- "nss_" - Super User
- "nsr_" - Reseller
- "nsd_" - Office Manager / Domain
- "nsu_" - Basic User / User
Random values (48 characters) - The main and middle part of the key is all random hash generated in a crypto safe way.
CRC Check (8 characters) - The last 8 characters are a CRC check of the first 52 characters. This adds to the length of the overall unknown random hash while also providing a way to validate if the key is formated correctly without checking a DB or running any more complex check function.

Key Usage

When using APIkey authentication you will need to provide the full length API key in the Authorization header with Bearer as well. This is very similar format to that of the Access Token and JWT token, though the API will be able to determine the correct logic to user based on the format or each type. An example full header implementation would be.

Authorization: Bearer nsu_ylP7TGZvubv2x3eO5fbHrLaByniJelnL0FRbHYKnevTvqIfC5897f65c

Key Storage

The Key that is generated and send to the develop on create request or through the Admin UI is not stored in plane text in the DB. it is only shown to the developer/admin 1 time before its stored in a non reversible hash in the DB in a similar way a user's password is stored that makes it impossible to extract it and read it back. The recommendation for the key storage on the application side would be to store it securely as possible without it being shown out to the user or making it available in anything like a browser cookie, javascript code, or anything that can be extracted. It should be excluded from any of the version controlled software as well living only on the production servers or lab.

Key ID

The Key ID is what is used to identify the key once its been created. It is created by using the first 12 characters of the full api key, but this is the only part that is stored in plane text. This id will be used for management of the key after its added as well as for logging including api logs and audit log.

Read Only

APIkeys can be configured with a read only flag. This when set to yes will modify the scope permissions and leave only Read and Count actions as supported preventing the Create, Update and Delete.

Revoking Access

Apikeys are not timed, but can easily be revoked cluster wide including a removal from cache on all servers with a simple api request to the revoke api. The only piece of data you need is the 12 character Key ID and authentication that allows you access to that ApiKey. That API is documented here, Revoke Apikey

Tracking Usage

Usage can be tracked with iNSight pro by key ID. The metric is "api_v2_apikey_requests" and will include the key Id as well as the instance (hostname) where the request are being made too.

Known Limitations

Site Manager is not currently a support Scope