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 Access 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 an access token that is used for all subsequent requests. To obtain this access 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": {}
}