Authentication keys for Zenoss API clients

A Zenoss API client (lower-case "client") is any application that uses the Zenoss API to gain access to Zenoss Cloud. These include:

• Streaming data clients, customized applications, or integrations that use the data receiver service to send entities, metric data points, or events to Zenoss Cloud.

• Customized integrations that use the user management service to create or update user accounts and groups.

• Customized applications or integrations that update or query the policy service, metric dictionary or any other Zenoss Cloud service supported by the Zenoss API.

An API Client (upper-case "Client") is a named object for managing authentication keys for Zenoss API clients (lower-case "client"). You create and manage API Clients on the ADMIN > API Clients page. Users with the Key Administrator role or the Manager role can create API Clients and then create authentication keys that "belong" to an API Client. Each API Client can have up to 200 keys.

You can create an API Client for Streaming Data Ingest API keys or for User Management API keys:

• Streaming Data Ingest API keys enable clients to use all Zenoss API services except the user management service.
• User Management API keys enable clients to use the user management service.

When an API Client is deleted, all of its keys are deleted, and clients using the keys are denied access within 60 seconds. API Client names are included in audit logs when Zenoss API clients update Zenoss Cloud. As a best practice, Zenoss recommends creating one API Client for each separate project or application.

Tips about authentication keys:

• Once created, a key cannot be retrieved. If a key is lost, the only recourse is to delete it and generate a new one.
• Zenoss recommends creating separate keys for individual services, microservices, and functions.
• The roles associated with the creator of a key for a Zenoss API client have no impact on the key's use.
• Keys do not expire when the key creator's account is removed.
• When a key is deleted, clients using the key are denied access within 60 seconds.

Generate a key

Use this procedure to generate an authentication key for a Zenoss API client. To perform it, your account must have the Key Administrator role or the Manager role.

1. Open the ADMIN > API Clients page.

2. Click GENERATE KEY.

   

   Tip

   The API address field displays the API endpoint for your organization.

3. In the Client name field, select an existing API Client or create a new one.

   • When you select an existing API Client, the API type field updates with the name of the API type associated with the API Client.

   • When you select Create new client, the dialog updates to include controls for specifying a new API Client.

     

     Enter a name and type, and then click SAVE. The dialog updates to remove controls for specifying a new API Client.

4. (Optional) In the Description field, enter text to associate with the key.

5. Click GENERATE KEY.

   The API key field updates with the new authentication key.

6. Copy the new key, and then save it in a secure storage location or service.

   Note

   Authentication keys cannot be retrieved. If a key is lost, the only recourse is to delete it and generate a new one.

7. Click CLOSE.

Delete an API Client

Use this procedure to delete an API Client and all its keys. To perform it, your account must have the Key Administrator role or the Manager role.

1. Open the ADMIN > API Clients page.

2. Use the table search fields to display the API Client to delete, or just scroll through the table.

3. In the Actions column, click the trash can icon.

4. In the pop-up dialog, click YES, DELETE API CLIENT.

Delete a key

Use this procedure to delete any individual Zenoss Cloud authentication key, for either a Zenoss API client or a Collection Zone API client.

To perform this procedure, your account must have the Key Administrator role or the Manager role. You can always delete keys for Collection Zone API clients that you created; see the Collection Zone key deletion procedure.

1. Open the ADMIN > API Clients page.

2. Use the table search fields to display the API Client with the key to delete, or just scroll through the table.

3. In the Actions column, click the eye icon.

   

4. In the API CLIENT DETAILS panel, click the trash can icon of the key to delete.

5. In the pop-up dialog, click YES, DELETE THE KEY.

Note

When you delete all the keys associated with an API Client for a Collection Zone API client, Zenoss Cloud deletes the API Client as well.