Skip to main content
Use the ZEDEDA CLI (ZCLI) to generate API tokens and view API usage from the command line. This article covers two command groups:
  • zcli api-token generates a session token that scripts and integrations can use to call the Edge Infrastructure Services API.
  • zcli api-usage shows how many API requests were made to each endpoint in a time range, and how many of them succeeded or failed.
This page is the command reference. For how tokens work, how long they last, and how to use them in API requests, see Authentication. To create and revoke tokens in the Edge Infrastructure Services console, see Profile Settings.

​
Before You Start

  • ZCLI is installed and authenticated against your enterprise. See Get Started.
  • To view API usage, you have a role that allows you to read API usage statistics. [TBD: confirm the minimum role required for zcli api-usage show, and whether cluster-wide statistics require a cloud-service administrator role.]

​
Generate an API Token

​
Generate a token for your enterprise

Generate an API token for the user who is logged in to ZCLI. The token carries the same permissions as your user account.
Example: generate a token that is valid for 30 days (43,200 minutes):
ZCLI prints the token on a single line:
Use the value after API-Token: as the Bearer token in API requests. See Use the Token in API Requests.
ZCLI prints the token in plain text in your terminal and does not save it anywhere. Copy it to a secure location, such as a secrets manager, before you clear the terminal. Anyone who has the token can call the API with your permissions until the token expires. ZCLI prints the token in the same format even if you set --format=json.
Keep the following in mind:
  • Enter --token-expiry in minutes, not seconds. The Authentication page describes the API’s expires field in seconds, but ZCLI multiplies your value by 60. For example, --token-expiry=60 creates a token that is valid for one hour.
  • Enter --token-expiry as a whole number. A value such as 1h or 30.5 stops ZCLI with a Python error (ValueError) before the request is sent.
  • Your enterprise can set a maximum token lifetime. See Token Expiry and Rotation.
  • If the enterprise name is not found, Edge Infrastructure Services returns an error and no token is created.
The zcli api-token --help text has two errors. The Commands section lists the command as get-api-oken, and the example uses get-token. Neither name works. Use get-api-token, as shown on this page.

​
View API Usage

​
Show API usage statistics

Show the number of API requests per endpoint, with the number of successful and failed requests.
Flag names are case-sensitive. Write --enterpriseIDs and --userAgents exactly as shown. To show API usage with the default time range:
To show API usage for a specific time range:
To show API usage for one enterprise from a start time until now:
To find an enterprise ID, run zcli enterprise show <name>.
The zcli api-usage --help text documents the enterprise filter as --enterpriseID (singular) and does not describe --userAgents. Use --enterpriseIDs and --userAgents, as shown in the syntax line on this page.

​
Time zone

ZCLI reads --from and --to in the local time zone of the system where ZCLI runs, and converts them to UTC before it sends the request. In the ZCLI container, the local time zone is usually UTC. If a value is not in the format YYYY-MM-DD HH:MM:SS, ZCLI prints input datetime in format %Y-%m-%d %H:%M:%S and stops.

​
Read the output

The text output starts with a line that shows what the statistics cover:
  • (Cluster Wide) when the statistics are not filtered by enterprise.
  • (Enterprise (IDs: [...])) with the enterprise IDs when they are.
A table follows, with one row per API endpoint: To see the full response, including the count for each HTTP status code, add the global --format=json option:

​
Next Steps

Authentication

Token scope, expiry, rotation, and how to use a token in API requests.

ZEDEDA API Overview

The services and versions of the Edge Infrastructure Services API.

Get Started

Install ZCLI, configure access to Edge Infrastructure Services, and sign in.

Overview

All ZCLI command procedures, organized by resource type.