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"

ℹ️
Note that this is not a bearer token, so there is no Bearer in the Authorization header.

Managing 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. Users can assign each key zero or more API scopes, which grant access to 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 it
Last Modified: Last update timestamp (UTC)
Last Accessed: Last usage timestamp (UTC)
Assigned 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.

ℹ️
CloudZero does not automatically grant access to new API endpoints. When new endpoints are released, Organizers must edit each API key to manually add the necessary scopes.

Create a new API key

To create an API key:

Navigate to Settings > API Keys.
Select Create New API Key.
Enter a name for the key.
Enter a description.
Select the appropriate API Key Scopes to assign specific permissions to the key. You must select at least one. For information about the scopes required for each endpoint, refer to the section API key scopes.
Select Create API Key.
Copy the API key displayed. It will not be shown again.
Select Close.

New keys are Enabled by default.

Edit an API key

To edit an API key's name and/or scopes:

On the API Keys page, locate the key you plan to modify.
Select the three-dot icon in the Actions column.
Select Edit.
Modify the API Key Name if needed.
Modify the Description if needed.
Select the appropriate API Key Scopes to assign specific permissions to the key. For information about the scopes required for each endpoint, refer to the section API key scopes.
Select Update API Key.

CloudZero displays the updated list of API keys.

Enable or disable an API key

To disable or enable an API key:

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

The Status column is updated to display Enabled or Disabled for the key you modified.

Delete an API key

⚠️
Deleting an API key will immediately revoke access for any services using it.

To delete an API key:

On the API Keys page, locate the key you plan to delete.
Select the three-dot icon in the Actions column.
Select Delete.
Type the name of the API key to confirm deletion.
Select Delete API Key.

CloudZero displays the message API Key deleted successfully and removes the key from the list of keys.

API key scopes

CloudZero supports the following API scopes, which correspond to specific API endpoints:

billing:read_costs: Get billing costs
billing:read_dimensions: Get billing dimensions
budgets:create_budget: Create budget
budgets:delete_budget: Delete budget
budgets:read_budget: Get one budget
budgets:read_budgets: Get a list of budgets
budgets:update_budget: Update a budget
connections:create_billing: Create a billing connection
connections:create_billing_anycost_billing_drop: Create an AnyCost Stream connection billing drop
connections:create_billing_anycost_validate_billing_drop: Validate an AnyCost Stream connection billing drop
connections:delete_billing: Delete a billing connection
connections:read_billing: Get one billing connection
connections:read_billing_anycost_billing_drops: Get a list of billing drops for an AnyCost Stream connection
connections:read_billing_anycost_billing_drops_month: Get contents of one billing drop for an AnyCost Stream connection
connections:read_billings: Get a list of billing connections
connections:update_billing: Update a billing connection
container-metrics_v1:abandon: Required scope for the CloudZero Agent for Kubernetes
container-metrics_v1:get-status: Required scope for the CloudZero Agent for Kubernetes
container-metrics_v1:legacy: Required scope for the CloudZero Agent for Kubernetes
container-metrics_v1:upload: Required scope for the CloudZero Agent for Kubernetes
costformation:create_definition_version: Create a CostFormation definition version
costformation:read_definition_version: Get one CostFormation definition version
costformation:read_definition_versions: Get a list of CostFormation definition versions
events_v1:create_event: Post an event
insights:create_insight: Create an insight
insights:create_insight_comment: Create a comment for an insight
insights:delete_insight: Delete an insight
insights:read_insight: Get one insight
insights:read_insight_comments: Get a list of comments for an insight
insights:read_insights: Get a list of insights
insights:update_insight: Update an insight
insights:update_insight_comment: Update a comment for an insight
unit-cost_v1:manage_telemetry_records:
- Allocation telemetry streams:
  - Post allocation telemetry records and create stream if it does not exist
  - Sum allocation telemetry records and create stream if it does not exist
  - Replace allocation telemetry records and create stream if it does not exist
  - Delete allocation telemetryrecords
- Unit cost metric telemetry streams:
  - Post unit cost metrics records and create stream if it does not exist
  - Sum unit cost metrics records and create stream if it does not exist
  - Replace unit cost metrics records and create stream if it does not exist
  - Delete unit cost metrics records
unit-cost_v1:delete_telemetry_stream: Delete a telemetry stream
unit-cost_v1:read_telemetry:
- Get recently processed records for an allocation or unit cost metric stream (Get telemetry stream records)
- Get recently submitted records for an allocation or unit cost metric stream (Get metrics records)
views:read_view: Get one view
views:read_views: Get a list of views