Skip to content

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 agents, customized applications, or integrations that use the Zenoss API to send models, data points, or events to Zenoss Cloud.
  • Customized integrations that use the user management methods to create or update user accounts and groups.
  • Customized applications or integrations that update or query the policy engine, 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.

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.
  • As a best practice, 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.

Creating an API Client

Use this procedure to create an API Client. To perform it, your account must have the Key Administrator role or the Manager role.

Follow these steps:

  1. In Zenoss Cloud, navigate to ADMIN > API Clients.

  2. Click ADD CLIENT.

  3. In the Name field, enter a name for the API Client.

    The name appears in audit logs and can be changed at any time.

  4. From the list in the API field, select an API.

  5. In the upper-right corner of the window, click SAVE.

Creating keys

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

  1. In Zenoss Cloud, navigate to ADMIN > API Clients.

  2. Use the pointer to hover over an existing API Client.

    If there are no API Clients or you wish to create a new one, see Creating an API Client.

  3. Click Generate Key.

  4. Optional: In the Description field, enter a description of the key or its use context.

  5. Click GENERATE KEY.

  6. When the key appears, copy it, and then save the key in a secure storage location or service.

    Warning

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

  7. In the upper-right corner, click X.

    The API Client is updated with information about the new key.

    Note

    Unlike keys for Collection Zone API clients, the roles associated with the creator of a key for a Zenoss API client have no impact on the key's use.

Deleting 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. In Zenoss Cloud, navigate to ADMIN > API Clients.

  2. Use the pointer to hover over the API Client to delete.

  3. Click the trash can icon.

  4. In the upper-right corner, click DELETE.

Deleting keys

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. In Zenoss Cloud, navigate to ADMIN > API Clients.

  2. Click the plus symbol of the API Client that contains the key or keys to delete.

    The following example shows one user's keys for Collection Zone API clients:

  3. Use the pointer to hover over the key to delete.

  4. Click the trash can icon.

  5. Click DELETE.