Control Plane API

Control Plane API enables programmatic management of deployments and environments in Cube Cloud. You can use it to list deployments, manage environments, and generate JWT tokens for accessing Core Data APIs.

Control Plane API is only available in Cube Cloud.

Prerequisites

Authentication

Control Plane API uses API key authentication. Include your API key in the Authorization header with the Api-Key prefix:


curl \
  -H "Authorization: Api-Key YOUR_API_KEY" \
  https://YOUR_CUBE_CLOUD_HOST/api/v1/deployments

Error handling

In case of an error, Control Plane API returns a JSON object with an error property:


{
  "error": "Error message"
}

Pagination

Endpoints that return lists support pagination using offset and limit query parameters:

Parameter	Description
`offset`	Number of items to skip. Default: `0`
`limit`	Maximum number of items to return. Default: `20`

Paginated responses include a pagination object:


{
  "data": [...],
  "pagination": {
    "offset": 0,
    "limit": 20,
    "total": 42
  }
}

Reference

`/api/v1/deployments`

Send a GET request to list all deployments accessible to the authenticated user.

Query parameters:

Parameter	Description	Required
`offset`	Pagination offset	No
`limit`	Pagination limit	No

Example request:


curl \
  -H "Authorization: Api-Key YOUR_API_KEY" \
  "https://YOUR_CUBE_CLOUD_HOST/api/v1/deployments"

Example response:


{
  "data": {
    "deployments": [
      {
        "id": "123",
        "name": "My Deployment",
        "created_at": "2024-01-15T10:30:00.000Z"
      }
    ]
  },
  "pagination": {
    "offset": 0,
    "limit": 20,
    "total": 1
  }
}

`/api/v1/deployments/{deployment_id}/environments`

Send a GET request to list environments for a specific deployment.

Path parameters:

Parameter	Description
`deployment_id`	The deployment ID

Query parameters:

Parameter	Description	Required
`type`	Filter by environment type: `production`, `staging`, or `development`	No
`offset`	Pagination offset	No
`limit`	Pagination limit	No

Example request:


curl \
  -H "Authorization: Api-Key YOUR_API_KEY" \
  "https://YOUR_CUBE_CLOUD_HOST/api/v1/deployments/123/environments"

Example response:


{
  "data": {
    "environments": [
      {
        "id": "456",
        "name": "Production",
        "type": "production",
        "api_credentials": {
          "rest": {
            "url": "https://example.cubecloud.dev/cubejs-api"
          },
          "sql": {
            "host": "example.sql.cubecloud.dev",
            "port": 5432
          }
        }
      }
    ]
  },
  "pagination": {
    "offset": 0,
    "limit": 20,
    "total": 1
  }
}

`/api/v1/deployments/{deployment_id}/environments/{environment_id}/tokens`

Send a POST request to create a JWT token for accessing Core Data APIs. The generated token can be used to authenticate requests to the REST API and Metadata API.

Path parameters:

Parameter	Description
`deployment_id`	The deployment ID
`environment_id`	The environment ID

Request body:

Property	Type	Description	Required
`security_context`	`object`	Security context to embed in the token	Yes
`expires_in`	`number`	Token expiration time in seconds. Default: `86400` (24 hours)	No

Example request:


curl \
  -X POST \
  -H "Authorization: Api-Key YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "security_context": {"tenant_id": "acme"},
    "expires_in": 3600
  }' \
  "https://YOUR_CUBE_CLOUD_HOST/api/v1/deployments/123/environments/456/tokens"

Example response:


{
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "created_at": "2024-01-15T10:30:00.000Z",
    "expires_at": "2024-01-15T11:30:00.000Z"
  }
}

Was this page useful?