Get Started

This document provides an overview of the Quave ONE API and how to use it.

Base URL

The base URL for all requests is https://api.quave.cloud/api/public/v1.

Authentication

The Public API accepts either a legacy Quave ONE token or an OAuth 2.1 access token. Both forms remain available by default, so existing CLI, CI, and API integrations do not need to change when an account starts using OAuth.

Legacy user and environment tokens

Use the existing authorization header format for a user token from your profile or an environment token from the app environment settings page. Some endpoints accept only a user token.

curl \
  -H 'Authorization: YOUR_LEGACY_TOKEN' \
  'https://api.quave.cloud/api/public/v1/app-env/status?envName=myapp-production'

Legacy tokens keep their existing behavior and permissions. They are not OAuth bearer tokens and do not need to be exchanged or re-created just to use this API.

OAuth 2.1 access tokens

OAuth clients use the Authorization Code flow with PKCE. Discover the Public API protected-resource metadata at https://api.quave.cloud/.well-known/oauth-protected-resource, then use the advertised authorization server and request this resource indicator:

https://api.quave.cloud

The authorization server currently advertises and serves these OAuth endpoints from the Quave ONE dashboard origin:

Purpose	Endpoint
Authorization server metadata	https://app.quave.cloud/.well-known/oauth-authorization-server
Dynamic Client Registration	https://app.quave.cloud/oauth/clients/register
Authorization	https://app.quave.cloud/oauth/authorize
Token exchange and refresh	https://app.quave.cloud/oauth/token
Revocation	https://app.quave.cloud/oauth/revoke

Use Dynamic Client Registration only when your integration’s complete redirect URI set matches a trusted Quave ONE callback profile. Custom Public API integrations usually use a static client ID created by a Quave ONE administrator. Public clients use PKCE and do not need a client secret. Confidential clients should protect any issued secret like any other credential.

At authorization time, include:

• response_type=code
• client_id
• redirect_uri matching the registered client
• code_challenge and code_challenge_method=S256
• resource=https://api.quave.cloud
• one or more requested capability scope values
• state for CSRF protection

After the user approves the requested capabilities, send the resulting access token with the standard Bearer format:

curl \
  -H 'Authorization: Bearer YOUR_OAUTH_ACCESS_TOKEN' \
  'https://api.quave.cloud/api/public/v1/app-env/status?envName=myapp-production'

OAuth access tokens are audience-bound. A token issued for the Public API can be used only with the Public API; a token issued for https://mcp.quave.cloud/ can be used only with MCP. A client that uses both resources receives separate grants that can be reviewed or revoked separately in User Menu → MCP → Connected apps.

OAuth permissions are stable Quave ONE capabilities, not one scope per REST endpoint or MCP tool:

Capability	Allows
quave:read	Read apps, environments, logs, metrics, and account data.
quave:read:secrets	Read secret environment values and other sensitive data.
quave:write:config	Change configuration, variables, and settings.
quave:write:deploy	Build, deploy, restart, scale, and run workloads.
quave:write:dangerous	Delete resources and perform irreversible operations.
quave:manage:mcp-keys	Manage MCP keys within the caller's effective access.
quave:admin	Perform account-level administrative operations.

Every request still enforces the signed-in user's current account, application, and environment permissions. An OAuth grant cannot grant access that the user does not have in Quave ONE.

OAuth-only automated access policy

An account administrator can enable Require OAuth for automated API and MCP access in the account settings. This account-level policy rejects non-OAuth user tokens, environment tokens, and MCP keys when they access the Public API or MCP for that account. Dashboard access and OAuth-connected apps remain available. Existing non-OAuth credentials are not deleted, so disabling the policy restores their normal Public API/MCP behavior. Review OAuth grants in Connected apps; users continue to manage their MCP keys separately.

The CLI is intentionally outside this policy because it does not yet have an OAuth flow. CLI endpoints continue to accept their supported user and environment CLI tokens even when the account requires OAuth for Public API and MCP. Do not send a Bearer OAuth token to a CLI endpoint; use the Public API resource for OAuth integrations instead.

For MCP, the same capability catalog applies, but an OAuth grant can be created By permissions or By tools. Tool-mode grants are MCP-only and store an explicit selected-tool list. Individual MCP-tool controls never apply to Public API OAuth grants, where each endpoint is authorized by its capability requirements.

Environment-Specific Endpoints

For endpoints that require environment context (most app environment management endpoints), you must provide an environment identifier along with your token. You can use either:

• envName - The CLI environment name (e.g., account-myapp-production)
• appEnvId - The ID of the app environment

Both parameters can be provided in the query string (for GET requests) or request body (for POST/PUT/PATCH/DELETE requests). If both are provided, appEnvId takes precedence.

Example with envName:

curl -X GET \
    -H 'Authorization: YOUR_TOKEN' \
    'https://api.quave.cloud/api/public/v1/app-env/status?envName=myapp-production'

Example with appEnvId:

curl -X GET \
    -H 'Authorization: YOUR_TOKEN' \
    'https://api.quave.cloud/api/public/v1/app-env/status?appEnvId=5f7b1b7b7b7b7b7b7b7b7b7b'

Request Processing

Some requests are processed asynchronously.
In such cases, the response will be { "status": "Ok" }, but the operation will continue in the background.
Even if the response is successful, the operation may still be in progress.

For example, if you try to remove a host that doesn't exist, the response will still be { "status": "Ok" }, but the host will not be removed.