API server specification

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.

OpenAPI specification is available at Github.

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

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..."
}

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.

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 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, including those encoded in authentication objects, on disk or database. It also has no access to private keys when dealing with SSH key resources.

Provider support

The table below lists supported providers and capabilities.

(*) OAuth can be used via Web application interface.

Resource type map

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

Authorization roles

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.

Ultimately, access to cloud resources is managed by the cloud provider’s permissions granted to corresponding Personal Access Token or User.

Required provider-specific permissions

Important: always provide least permissive access to your resources.

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 partially fails.

Supported operations

For detailed resource schemas and additional API endpoints, refer to the OpenAPI specification.

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.5 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...

See the OpenAPI specification to find JSON schema of a concrete resource.