API Overview

This guide explains how to use the kopernik.us API as a standalone service. For console-specific guidance, see the Web Application Documentation.

See Terms of Use before using the service.

Overview

The kopernik.us REST API provides a unified way to discover and manage cloud resources across Akamai, AWS, and DigitalOcean.

Base URL:

https://api.kopernik.us/v0

Documentation Map

The documentation is split into three layers:

• API guides: descriptive pages for API concepts such as authentication, machines, VPCs, container apps, and actions
• API reference: generated OpenAPI reference for paths, parameters, and schemas
• Web application documentation: console workflows and UI behavior

Authentication Quick Start

To call the API, exchange provider credentials for a kopernik.us bearer token.

Your provider credentials must be able to read account identity information, because kopernik.us uses the provider account ID to build stable resource identifiers.

Provider credential setup:

• Akamai personal access tokens
• AWS access keys
• DigitalOcean personal access tokens

Exchange a provider token

Use POST /auth/authorize/{providerUid}. The optional accessLevel field is readwrite or readonly, and defaults to readwrite.

curl -sS \
  -X POST "https://api.kopernik.us/v0/auth/authorize/digitalocean" \
  -H "Content-Type: application/json" \
  -d '{
    "accessToken": "your-provider-token",
    "accessLevel": "readwrite"
  }'

Example response:

{
  "metadata": {
    "uid": "unique-request-id",
    "timestamp": 1697500000
  },
  "signedAuth": "eyJhbGc..."
}

Use the returned token in later requests:

Authorization: Bearer eyJhbGc...

Access levels

• readonly allows listing and reading resources
• readwrite additionally allows create and delete requests

kopernik.us enforces the declared access level, but provider-side permissions still determine what the underlying cloud API will allow.

Core Request Patterns

See the generated API reference for full request and schema details. The patterns below cover the common workflow.

List resources

curl -sS \
  "https://api.kopernik.us/v0/resource/machine/digitalocean?maxResults=20" \
  -H "Authorization: Bearer eyJhbGc..."

Get one resource

curl -sS \
  "https://api.kopernik.us/v0/resource/machine/digitalocean/12345678" \
  -H "Authorization: Bearer eyJhbGc..."

Start a long-running create operation

Most POST and DELETE resource operations are asynchronous.

curl -sS \
  -X POST "https://api.kopernik.us/v0/resource/machine/digitalocean?waitTime=5" \
  -H "Authorization: Bearer eyJhbGc..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-server",
    "regionUid": "nyc1",
    "imageUid": "ubuntu-22-04-x64",
    "machineTypeUid": "s-1vcpu-1gb"
  }'

If the action finishes within waitTime, the API returns 200. If it is still running, the API returns 202. In both cases the response body contains an Action.

Poll action status

curl -sS \
  "https://api.kopernik.us/v0/action/digitalocean/<actionUid>" \
  -H "Authorization: Bearer eyJhbGc..."

Resource Model

Most resources share these identity fields:

• type: normalized kopernik.us resource type
• providerUid: akamai, aws, or digitalocean
• regionUid: provider region, when the resource is regional
• accountUid: provider account identifier
• uid: provider-side resource identifier within the account or provider scope
• grid: globally unique kopernik.us resource identifier

Resource type map

Operation Model

Create and delete operations usually return Action objects rather than final resource payloads. For the full asynchronous execution model, see Actions and asynchronous operations.

Filters, Pagination, and Metadata

Pagination

List endpoints commonly support:

• nextToken to continue from a previous page
• maxResults to cap page size

When more results are available, the response includes nextToken.

JQ filters

List endpoints support JQ 1.7 expressions through the jq query parameter.

Example:

curl -sS \
  'https://api.kopernik.us/v0/resource/machinetype/akamai?jq=.name | contains("g7")' \
  -H "Authorization: Bearer eyJhbGc..."

Response metadata

Successful and error responses include:

• metadata.uid: request identifier
• metadata.timestamp: Unix timestamp in seconds

Error responses also include:

• reason: human-readable error details

Security Considerations

The API server has access only to resources provided by corresponding cloud provider’s API, and cannot access:

• your machine’s processes or memory,
• data stored on your accounts’s volumes, or machine disks,
• passwords or private SSH keys used for creating machine instances.

The server may log to disk request arguments and certain response fields, which may contain sensitive data, directly or indirectly. Example of such data includes: resource names, labels, tags, etc. Do not use sensitive data in your resource properties if this is a concern for you.

The API server never stores your API keys on disk or database. It also has no access to private keys when dealing with SSH key resources.

You can revoke Personal Access Token or OAuth token from your cloud provider’s account management page at any time. All tokens registered at the kopernik.us API server will be automatically invalidated.

Important: always provide least permissive access to your resources.

Provider Support

(*) OAuth can be used via Console / Accounts interface.

Required Provider-Specific Permissions

Notes:

(*) DigitalOcean Spaces authenticates with an S3 access key that is separate from the account’s main API credentials (the personal access token or OAuth token used by every other resource type). That key cannot be derived from the main credentials, so it must be attached to the account as its bucket service token — see Service tokens; bucket operations are refused until it is. The key needs Full Access: with a key limited to specific buckets, they fail with 403 and the error code insufficientServiceCredentials. Akamai Object Storage is managed with the account’s main credentials, and AWS S3 reuses the account’s existing access key.

For AWS, it is highly recommended to always provide *.Delete<Resource> permission along with *.Create<Resource> so that the API server can correctly rollback changes if Create operation succeeds partially.

Container apps also depend on the permissions needed to select images, machine types, regions, VPCs, SSH keys, and storage, because the API creates a backing machine on your behalf.

Supported Operations

(*) DigitalOcean requires separate object storage credentials, as described in Required Provider-Specific Permissions.

Further Reading

• API guides
• Authentication
• Machines
• Container Apps
• Actions and asynchronous operations
• OpenAPI reference index
• Auth API
• Action API
• Container App API
• App Template API