Skip to main content
All requests to the CUDO Compute API must be authenticated with an API key in the Authorization header unless explicitly documented otherwise.

​
Overview

The CUDO Compute API uses a simple API key based bearer scheme: Header format: 
Authorization: Bearer <api_key>
Your API key uniquely identifies you and inherits the permissions of your user or project context. Keep keys secret and never embed them in client-side code or public repositories.

​
Create an API key

You can create API keys in two ways:
  1. Via the CUDO Compute console (recommended for most users)
  2. Programmatically with the POST /v1/api-keys endpoint
  • cURL
  • Python (requests)
  • JavaScript (fetch)
curl -X POST https://api.cudocompute.com/v1/api-keys \
	-H "Authorization: Bearer <existing_api_key>" \
	-H "Content-Type: application/json" \
	-d '{ }'
Successful response (200):
{
	"id": "ak_12345",
	"key": "ck_live_XXXXXXXXXXXXXXXX",
	"createTime": "2025-10-14T12:34:56Z"
}
The key field is only returned once at creation time. Store it securely now; you cannot retrieve it later.

​
Using your API key

Include the header on every request: 
curl https://api.cudocompute.com/v1/billing-accounts \
	-H "Authorization: Bearer $CUDO_API_KEY"
Python example: 
import os, requests
API_KEY = os.getenv("CUDO_API_KEY")
resp = requests.get(
		"https://api.cudocompute.com/v1/billing-accounts",
		headers={"Authorization": f"Bearer {API_KEY}"},
		timeout=30,
)
print(resp.status_code, resp.json())

​
Error handling

Common authentication-related HTTP status codes:
CodeMeaningTypical Cause
400Bad RequestMalformed header or body
401UnauthorizedMissing / invalid / revoked API key
403ForbiddenAuthenticated but lacks permission for the resource
429Too Many RequestsRate limit exceeded (apply retry with backoff)
Our errors follow the Google AIP 193 specification. Please see the error codes and formats in the Errors section of the documentation.

​
Best practices

​
Rotation workflow example

  1. Create a new key.
  2. Deploy the new key (update environment variables / secret stores).
  3. Verify all services function with the new key.
  4. Revoke the old key.
This minimizes downtime and risk.

​
Environment variables

Store your key locally in a shell profile or an .env file: 
export CUDO_API_KEY="ck_live_XXXXXXXXXXXXXXXX"
Then reference it in tooling and scripts instead of hardcoding.

​
Rate limiting & retries

If you receive HTTP 429, implement exponential backoff (e.g., wait 1s, 2s, 4s, 8s…) and respect any Retry-After header (if present). Do not continuously retry invalid keys-fix the credential instead.

​
Troubleshooting

SymptomPossible CauseFix
401 UnauthorizedMissing headerAdd Authorization: Bearer ...
401 UnauthorizedTypo in key / whitespaceCopy key again; trim spaces/newlines
401 UnauthorizedRevoked keyGenerate a new key
403 ForbiddenInsufficient permissionsUse a key with required access or adjust roles
429 Too Many RequestsBursty trafficAdd client-side throttling & retry with backoff
Currently the API uses a single global bearer scheme named bearerAuth with header Authorization. There is no separate refresh or OAuth flow.

​
Next steps

You’re authenticated-explore the API reference or jump into building clusters, machines, and more.