API overview

This document describes usage of kopernik.us API server. For Web application documentation, see kopernik.us - Web Application Documentation.

See Terms of Use before using the service.

Overview

The kopernik.us REST API provides a unified interface for managing cloud resources across multiple providers: Akamai, AWS, DigitalOcean.

Quick start

Base URL: https://api.kopernik.us/v0

To access resources, you need to obtain an authentication token.

Create Personal Access Token at your cloud provider’s admin page, and exchange the token for a kopernik.us authentication token. Make sure the token allows read access to account information: API server needs to obtain account ID to provide consistent resource identifiers. See required permissions for details.

Personal access token how-to: Akamai, AWS, DigitalOcean

Use one of the following options to convert provider’s token into kopernik.us authentication token:

Option 1.

Send API request:

Request:

POST /auth/authorize/{providerUid}
Content-Type: application/json

{
  "accessToken": "your-provider-token",
  "role": "admin"
}

Response:

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

Option 2.

Navigate to Console / Accounts and add your cloud provider account. Authentication token will be available in the table.

Use the token

Include the signedAuth token in the Authorization header for all subsequent requests:

Authorization: Bearer eyJhbGc...

Accessing Resources

Once authenticated, you can perform operations on cloud resources. See OpenAPI specification to get operation and schema details.

List Resources

Retrieve a paginated list of resources for a specific provider:

GET /resource/{resourceType}/{providerUid}
Authorization: Bearer eyJhbGc...

Example:

GET /resource/machine/digitalocean
Authorization: Bearer eyJhbGc...

Response:

{
  "metadata": {
    "uid": "unique-request-id",
    "timestamp": 1697500000
  },
  "resources": [
    {
      "type": "machine",
      "providerUid": "digitalocean",
      "regionUid": "nyc1",
      "accountUid": "123456",
      "uid": "12345678",
      "grid": "grid:digitalocean:machine:nyc1:123456:12345678",
      "name": "web-server-01",
      "status": "active"
    }
  ]
}

Get Individual Resource

Retrieve a specific resource by its unique identifier:

GET /resource/{resourceType}/{providerUid}/{resourceUid}
Authorization: Bearer eyJhbGc...

Example:

GET /resource/machine/digitalocean/12345678
Authorization: Bearer eyJhbGc...

Response:

{
  "metadata": {
    "uid": "unique-request-id",
    "timestamp": 1697500000
  },
  "resource": {
    "type": "machine",
    "providerUid": "digitalocean",
    "regionUid": "nyc1",
    "accountUid": "123456",
    "uid": "12345678",
    "grid": "grid:digitalocean:machine:nyc1:123456:12345678",
    "name": "web-server-01",
    "status": "active"
  }
}

Create Resource

Create a new resource:

POST /resource/machine/{providerUid}
Authorization: Bearer eyJhbGc...
Content-Type: application/json

{
  "regionUid": "nyc1",
  "imageUid": "ubuntu-22-04-x64",
  "machineTypeUid": "s-1vcpu-1gb",
  "name": "my-server"
}

Delete Resource

Delete a specific resource:

DELETE /resource/{resourceType}/{providerUid}/{resourceUid}
Authorization: Bearer eyJhbGc...

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

The table below lists supported providers and capabilities.

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

Resource type map

List of kopernik.us resources and their provider-side entities.

Authorization roles and access

The endpoint to register a Personal Access Token accepts a role argument, which can be set to either "admin" or "readonly". The API server rejects POST and DELETE requests if the token was created without "admin" permissions.

Access to cloud resources is managed by the cloud provider’s permissions granted to corresponding Personal Access Token (or User, for AWS) regardless of the role chosen when registering a cloud account.

You can register a token with “admin” role at kopernik.us API server even if the token is not given write permissions, but then operations performed with such key may fail due to insufficient privileges.

Required provider-specific permissions

Notes

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.

Supported operations

Response Metadata

All successful responses include a metadata object with:

• uid - Unique identifier for the request
• timestamp - Unix timestamp of the response (seconds since epoch)

Error responses include the same metadata plus:

• reason - Error description string

Pagination

List endpoints support pagination through optional query parameters:

• nextToken - Token for the next page (provided in previous response)
• maxResults - Maximum number of results per page; actual returned page may have fewer items

When more results are available, the response includes a nextToken field.

Filters

List endpoints support JQ 1.7 expressions via jq query parameter. The expression is applied to each individual resource object. If the expression returns a “truthy” result (true, non-zero number, etc), then the object is returned.

Example: filter machine types to return only those containing “g7” in their name (URL is not encoded here):

GET '/resource/machinetype/akamai?jq=.name | contains("g7")'
Authorization: Bearer eyJhbGc...