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

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 Organizer role can manage keys. Organizers 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.

📘

Updating API Keys For New Endpoints

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.

Creating A New API Key

To create an API key:

1. Navigate to Settings > API Keys.

2. Select Create New API Key.

   

3. Enter a name for the key.

4. Enter a description.

5. Select the appropriate API Key Scopes to assign specific permissions to the key. You must select at least 1.

   

6. Select Create API Key.

7. Copy the API key displayed.

   ⚠️

   WARNING

   The API key will not be shown again.

   

8. Select Close.

New keys are Enabled by default.

Editing An API Key

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

1. From the API Keys page, locate the key you plan to modify.

2. Select the three-dot icon in the Actions column.

   

3. Select Edit.

4. Modify the API Key Name if needed.

5. Modify the Description if needed.

6. Select the appropriate API Key Scopes to assign specific permissions to the key.

   

7. Select Update API Key.

CloudZero displays the updated list of API keys.

Disabling Or Enabling An API Key

To disable or enable an API key:

1. From the API Keys page, locate the key you plan to modify.

2. Select the three-dot icon in the Actions column.

   

3. Select Disable or Enable.

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

Deleting An API Key

⚠️

WARNING

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

To delete an API key:

1. From the API Keys page, locate the key you plan to delete.

2. Select the three-dot icon in the Actions column.

   

3. Select Delete.

4. Type the name of the API key to confirm deletion.

   

5. 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 records and create stream if it doesn't exist
    • Sum allocation telemetry records and create stream if it doesn't exist
    • Replace allocation records and create stream if it doesn't exist
    • Delete allocation records
  • Unit cost metric telemetry streams:
    • Post unit cost metric records and create stream if it doesn't exist
    • Sum unit cost metric records and create stream if it doesn't exist
    • Replace unit cost metric records and create stream if it doesn't exist
    • Delete unit cost metric records
• unit-cost_v1:create_telemetry_stream: Create a telemetry stream
• 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 recently submitted records for an allocation or unit cost metric stream
• views:read_view: Get one view
• views:read_views: Get a list of views