Authentication

This page explains how authentication works in the kopernik.us API.

For endpoint and schema details, see the Auth API reference. For console-based account setup, see the Accounts console guide.

Purpose

The API does not use your cloud provider token directly on every request. Instead, you exchange provider credentials for a kopernik.us bearer token and then use that token in the Authorization header.

This gives the service a consistent auth model across providers while still preserving provider-specific account identity and permissions.

Authentication flow

The common flow is:

Create or obtain provider credentials.
Send them to the auth API.
Receive signedAuth.
Use Authorization: Bearer <signedAuth> in later requests.

Provider credentials

Supported inputs depend on the provider:

Akamai: personal access token or OAuth through the console
AWS: access key credentials
DigitalOcean: personal access token or OAuth through the console

Your provider credentials must be able to read account identity information, because the API needs the provider account ID to construct stable resource identifiers.

Access level

The auth request includes accessLevel. It is optional and defaults to readwrite.

Supported values:

readonly: allows list and get operations
readwrite: allows create and delete operations in addition to read operations

This access level is enforced by kopernik.us. Provider-side permissions are still checked by the cloud provider when the underlying operation runs.

Service tokens

Some provider services do not accept the account’s main credentials. Object storage on DigitalOcean (Spaces) needs its own S3-compatible access key. A provider reports this in its static data as customCredentials: true for the resource type, for example limits.service.bucket.

Pass such credentials in serviceTokens, keyed by resource type, together with the personal access token. Give a key pair as <accessKeyId>/<secretAccessKey>:

{
  "accessToken": "<personal access token>",
  "accessLevel": "readwrite",
  "serviceTokens": {
    "bucket": { "accessToken": "<accessKeyId>/<secretAccessKey>" }
  }
}

The returned signedAuth carries the service tokens. To change them, authorize again with the full set. In the web console, service tokens are attached to and detached from a signed-in account under Service credentials on the account’s details page, which uses PUT and DELETE on /auth/service-tokens/{resourceType}.

Region-scoped authentication

Some providers expose region-sensitive behavior in authentication or follow-up operations. When required, auth requests can include regionUid.

AWS is the main case where regional context matters.

Console versus direct API use

You can authenticate in two ways:

directly through the auth endpoints if you are writing scripts or external clients
through the web console, which stores the auth context for browser use

The console is convenient for exploration. Direct API auth is better for automation and integration work.