Authorization

CloudZero uses key-based authorization to secure API access. To authenticate your requests, include your API key in the Authorization header:

curl -X GET https://api.cloudzero.com/v2/insights \
  -H "Authorization: AbCd1234EfGh5678AbCd1234EfGh5678AbCd12"

Manage API keys

An organization can have multiple API keys. To view and manage all API keys for your organization, navigate to Settings > API Keys.

Only users with the necessary permissions can manage keys. Each key can be assigned one or more API scopes, which grant access to specific endpoints in the CloudZero API.

The API Keys page displays a list of keys with the following information:

• Name
• Description
• Created By: Email of the user who created the key
• Updated By: Email of the user who last modified the key
• Last Modified: Last update timestamp
• Last Accessed: Last usage timestamp, or "Not In Use" if the key has never been used
• Scopes: Number of granted API scopes
• Status: Enabled or Disabled

If your organization had an API key before multiple keys were supported, it is listed as Legacy API Key.

Create an API key

1. Navigate to Settings > API Keys.

2. Select Create API Key.

3. Enter a name for the key (minimum 3 characters, must be unique).

4. Enter a description (optional).

5. Under Scopes, choose how the key is scoped. See Fixed and managed scopes for which to pick.

   • Managed scopes: select one or more use cases, such as Send AI Telemetry. CloudZero keeps the key's scopes current as new endpoints ship.
   • Fixed scopes: select each scope individually. You must select at least one. Scopes are grouped into categories under six blocks, such as Read cost data and Configure. Use the search bar or expand categories to find specific scopes. For information about each scope, refer to API key scopes.

6. Select Create API Key.

7. Copy the API key displayed. It will not be shown again.

8. Select Done.

New keys are Enabled by default.

Edit an API key

1. On the API Keys page, locate the key you want to modify.
2. Click the key name, or select the three-dot icon in the Actions column and select Edit.
3. Modify the Name, Description, or Scopes as needed. For information about each scope, refer to API key scopes.
4. Select Save Changes.

On a key that uses fixed scopes, a save that removes a scope or adds a replacement opens a Save scope changes dialog. It lists the replacements, the other scopes you added, and the scopes you removed. Select Save changes to confirm, or Cancel to keep editing.

Update out-of-date scopes

A key can hold a scope that is no longer Current (see Scope states). On the API Keys page, such a key shows a badge next to its name, such as 1 out of date. The count includes both Retired and Removed scopes.

To update the key:

1. Click the key name to open the Update API Key panel.
2. Above the scope list, a notice lists each out-of-date scope with a Retired or Removed badge. When a scope has a replacement, the notice names it.
3. Add the replacement:
   • For a Retired scope, select Use replacement where the notice offers it. The button checks the replacement and unchecks the Retired scope.
   • For a Removed scope, check the replacement in the scope list, then uncheck the Removed scope in the notice.
4. Select Save Changes, then confirm in the Save scope changes dialog.

Nothing changes on the key until you save. If you close the panel without saving, the key keeps every scope it had, and its Retired scopes keep working.

When a scope has no replacement, the notice says "No replacement exists." To drop the scope, uncheck it. Unchecking a Retired scope removes access the key still has. Unchecking a Removed scope changes nothing the key can reach today.

Enable or disable an API key

1. On the API Keys page, locate the key you want to modify.
2. Select the three-dot icon in the Actions column.
3. Select Enable or Disable.

The Status column updates to reflect the change.

Delete an API key

1. On the API Keys page, locate the key you want to delete.
2. Select the three-dot icon in the Actions column.
3. Select Delete.
4. Type the exact name of the API key to confirm deletion.
5. Select Delete.

Fixed and managed scopes

Every API key is scoped one of two ways. A key uses either fixed scopes or managed scopes, never both.

Managed scopes grant a use case rather than a list of endpoints. You select Send AI Telemetry or Send Billing Data, and CloudZero maintains the underlying scopes for you. When a new endpoint ships within that use case, keys already referencing it gain access without any edit. This is the better choice for send-only integrations, where the alternative is discovering later that a key was silently missing an endpoint added after it was issued.

Managed scopes are offered only for use cases that exclusively accept data. These endpoints return nothing about your organization beyond whether a submission was accepted, so widening one cannot expose data a key could not already send.

Fixed scopes grant exactly the scopes you select and nothing more. New endpoints are never added automatically, so a key keeps the same permissions until you edit it. Choose fixed scopes when a key reads organization data, when you need permissions narrower than a whole use case, or when an audit requires the grant to be an explicit, unchanging list.

API key scopes

The scopes below apply to keys that use fixed scopes. CloudZero organizes them into categories, grouped into six blocks named for what a key with those scopes can do. Each scope grants access to specific API endpoints. When creating or editing an API key, select the scopes that match how the key will be used.

AI

Ask questions, send AI telemetry

AI Hub (MCP)

Access the CloudZero AI Hub over MCP for AI assistants and agents.

This one scope covers every AI Hub tool your organization has enabled, with access to all of your organization's data. Role-based data access filters and permission set restrictions do not apply to API keys. Tools can read (for example, cost data, dimensions, telemetry, optimization recommendations, realized savings, resource metadata, and CostFormation definitions) and write (for example, managing organization context and logging Insights). To apply each person's data access and permissions, have them sign in individually instead (browser sign-in or an MCP OAuth client).

Send AI Telemetry

Ingest AI inference telemetry from any source.

AI Device Control Plane

Enroll AI telemetry devices and report their liveness.

Send data in

Send usage, telemetry and billing data in

Telemetry & Usage Streams

Create and manage unit-cost telemetry streams and record engineering events.

Kubernetes Agent

Send-only permissions for the CloudZero Kubernetes agent to upload container metrics.

Send Billing Data

Send billing data to an already-established connection.

Read cost data

Read cost data and manage saved Views

Cost & Usage Data

Read cost, usage, dimension, and resource-tag data via the API.

Views

Create, read, update, and delete saved Views.

Act on cost

Create and change budgets, insights, recommendations, monitors

Insights & Anomalies

Create, read, update, and comment on cost anomalies / insights.

Budgets

Create, read, update, and delete budgets.

Optimization & Savings

Read and manage savings recommendations and their comments.

Monitors & Incidents

Read and manage cost monitors and the incidents they raise.

Configure

Change how cost is allocated and where data comes from

Cost Allocation (CostFormation)

Manage CostFormation definitions, namespaces, and publish jobs for cost allocation.

Manage Billing Connections

Create, read, update, and delete billing connections, and read what AnyCost connections have received.

Kubernetes Clusters

Read Kubernetes clusters and the cost of their workloads, and hide or show clusters. Not required by the Kubernetes agent to send data.

Administer

Change who can do any of the above

Roles & Access Control

Manage CloudZero roles and read permission sets via the API.

Scope states

Every scope has a state: Current, Retired, or Removed. The state decides whether the scope can be granted, and whether it still works for a key that already holds it.

A Retired or Removed scope can name a replacement scope, which is always Current. Every scope listed on this page is Current. To move a key off a Retired or Removed scope, see Update out-of-date scopes.