Skip to main content

​
Overview

Two APIs are available:
  • Core API - Main API for managing Control Plane resources
  • Audit API - API for querying and creating audit events

​
API Endpoints

APIEndpoint URLFallback Swagger API Documentation
Corehttps://api.cpln.io/https://console.cpln.io/openapi/core
Audithttps://audit.cpln.io/audithttps://console.cpln.io/openapi/audit

​
Authentication

The Control Plane APIs use Bearer token authentication. All API requests must include an authorization header with a valid token.

​
Obtaining Authorization Tokens

You can authenticate using one of the following methods:

​
Service Account Key

Create a service account in your organization with the necessary permissions, then generate a service account key. This key can be used as an API token.

​
User Refresh Token

If you’re using the Control Plane CLI, first log in by running cpln login. This opens a browser where you can authenticate using your identity provider (Google, Microsoft, etc.). After logging in, your CLI profile receives a refresh token that is used for all subsequent requests. To obtain this refresh token, run: 
cpln profile token <profile-name>
Replace <profile-name> with the name of your logged-in CLI profile. Use the returned token as your authorization token.

​
Using Authentication

Include your token in the Authorization header of all API requests: 
Authorization: Bearer YOUR_TOKEN_HERE
Example with cURL: 
curl --request GET \
  --url https://api.cpln.io/org/{org}/gvc/{name} \
  --header 'Authorization: YOUR_TOKEN_HERE'

​
Using the Interactive API Playground

Each endpoint in this documentation includes a “Try it” button that opens an interactive API playground. You can use this to:
  1. Test endpoints directly - Make live API calls without leaving the documentation
  2. See request/response examples - View formatted JSON responses
  3. Copy code samples - Get ready-to-use cURL, Python, or JavaScript examples

​
Example: Getting a GVC

To get a GVC (Global Virtual Cloud) using the interactive playground:
  1. Navigate to the GVC section in the Core API
  2. Click on “Get a GVC by name”
  3. Click the green “Try it” button
  4. Enter your authorization token in the authentication field
  5. Fill in the required parameters:
    • org: Your organization name (e.g., my-org)
    • name: The name of your GVC (e.g., my-gvc)
  6. Click “Send” to execute the request
The response will display the GVC details in JSON format, which you can copy or use as a reference for your own API calls.

​
Example Request

Here’s a complete example of getting a GVC using cURL: 
curl --request GET \
  --url https://api.cpln.io/org/my-org/gvc/my-gvc \
  --header 'Authorization: YOUR_TOKEN_HERE'
Successful response: 
{
  "kind": "gvc",
  "id": "aac813e3-0fef-423f-9dcd-630f5a59e56a",
  "name": "my-gvc",
  "alias": "a1gm4cx40er00",
  "description": "my-gvc",
  "version": 12,
  "tags": {},
  "created": "2024-01-10T21:50:46.156Z",
  "lastModified": "2025-11-20T13:09:31.150Z",
  "spec": {
    "env": [
      {
        "name": "KEY",
        "value": "VALUE"
      }
    ],
    "loadBalancer": {
      "trustedProxies": 0
    },
    "staticPlacement": {
      "locationLinks": ["/org/my-org/location/aws-eu-central-1"]
    }
  },
  "links": [
    {
      "rel": "self",
      "href": "/org/my-org/gvc/my-gvc"
    },
    {
      "rel": "org",
      "href": "/org/my-org"
    },
    {
      "rel": "workload",
      "href": "/org/my-org/gvc/my-gvc/workload"
    },
    {
      "rel": "identity",
      "href": "/org/my-org/gvc/my-gvc/identity"
    }
  ],
  "status": {}
}