Overview

API Keys are an ideal method for server-to-server communication, where the credentials can be kept secure and, therefore, can remain untimed. The ability to send a nonchallenged initial request for data provides a quicker response. API keys remain scoped as well, so you can use them with most levels of authentication, from Basic User to Super User.

Key Format

The API Key itself will be autogenerated on creation 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. It will also identify the scope level in use to help a developer understand the expected restrictions.
• Random Values 48 characters)—The main and middle parts of the key are all random hashes 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 formatted correctly without checking a DB or running any more complex check function.

Key Usage

You must also provide the full-length API key in the Authorization header with Bearer when using API key authentication. This format is very similar to that of the Access Token and JWT token, though the API will be able to determine the correct logic for the user based on the format of each type. An example of full header implementation would be. 

Header

Authorization: Bearer nsu_ylP7TGZvubv2x3eO5fbHrLaByniJelnL0FRbHYKnevTvqIfC5897f65c

Key Storage

The Key that is generated and sent to the developer on a create request or through the Admin UI is not stored in plain text in the DB. It is only shown to the developer/admin 1 time before it's stored in a non-reversible hash in the DB in a similar way a user's password is stored, which 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 as 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 version-controlled software and living only on the production servers or lab.

Key ID

The Key ID is used to identify the key once it has been created. It is created using the first 12 characters of the full API key, but this is the only part stored in plain text. This ID will be used to manage the key after it is added and for logging, including API logs and audit logs.

Read Only

API keys can be configured with a read-only flag. When set to yes, this will modify the scope permissions and leave only Read and Count actions as supported, preventing Create, Update, and Delete.

Revoking Access

API keys are not timed but can easily be revoked cluster-wide, including removal from the cache on all servers with a simple API request to the revoke API. The only data you need is the 12-character Key ID and authentication allowing access to that API Key. 

Tracking Usage

Usage can be tracked using a key ID. The metric is "api_v2_apikey_requests" and will include the key ID and the instance (hostname) where the requests are being made.