Skip to main content

​
Overview

The Management API lets you create Cavos apps directly from your backend, CI/CD pipeline, or any HTTP client — without going through the dashboard. All requests authenticate with an API key scoped to a specific organization.
API keys are generated from your organization settings in the Dashboard. Each key is shown only once at creation and cannot be recovered.

​
Authentication

Include your API key as a Bearer token in every request: 
Authorization: Bearer cav_your_api_key_here
Key format: cav_ followed by 48 URL-safe characters.
API keys are scoped to a single organization. A key for org A cannot create apps in org B.

​
Endpoints

​
Create an App

curl -X POST https://cavos.xyz/api/v1/apps \
  -H "Authorization: Bearer cav_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My App",
    "organization_id": "your-org-uuid",
    "description": "Optional description"
  }'
Endpoint 
POST https://cavos.xyz/api/v1/apps
Request body
FieldTypeRequiredDescription
namestringYesDisplay name for the app
organization_idstring (UUID)YesThe org this app belongs to — must match the API key’s org
descriptionstringNoOptional description
Success response — 201 Created 
{
  "app": {
    "id": "3f7a9b2e-...",
    "name": "My App",
    "description": "Optional description",
    "organization_id": "your-org-uuid",
    "is_active": true,
    "created_at": "2026-02-13T12:00:00Z"
  }
}
The returned app.id is the App ID you pass to the Cavos SDK (appId in CavosProvider).

​
Error Reference

StatusCodeMeaning
400—Missing or invalid fields (name or organization_id)
401—Missing, malformed, or revoked API key
403—API key doesn’t have access to the requested organization
404—Organization not found
429—App limit reached for your plan (see below)
500—Internal server error
Example error responses
401 Invalid key
{ "error": "Invalid or revoked API key" }
403 Wrong org
{ "error": "API key does not have access to this organization" }
429 Limit reached
{
  "error": "App limit reached for your plan",
  "tier": "developer",
  "limit": 10,
  "current": 10
}

​
Plan Limits

App creation limits apply per user account, across all their organizations.
PlanApp Limit
Developer (free)10 apps
Growth30 apps
Scale100 apps
Upgrade your plan from the Billing page.

​
Generating an API Key

  1. Go to your Dashboard and open an organization
  2. Scroll to the API Keys section
  3. Click Generate Key and give it a descriptive name (e.g. "CI Pipeline")
  4. Copy the key — it’s shown only once
API Keys section in the organization dashboard
To revoke a key, click Revoke next to it in the dashboard. Revoked keys are rejected immediately.

​
Security Best Practices

Never hardcode API keys in source code. Use environment variables or a secrets manager:
# .env
CAVOS_API_KEY=cav_your_api_key_here

headers: { 'Authorization': `Bearer ${process.env.CAVOS_API_KEY}` }
Generate a separate key for each consumer (CI pipeline, backend service, etc.). This way you can revoke a single key without affecting others.
Generate a new key, update your service, then revoke the old one. The API supports multiple active keys per organization.
Keys in logs, error messages, or frontend bundles are compromised. Treat them like passwords.