Authentication API

API for authentication operations

Version: 0.1.0

Server

  • URL: https://api.kopernik.us/v0
    • Kopernik.us API server

Paths

/auth/authorize/{providerUid}

POST

Authorize token

Validate authentication token and return authentication object which can be used in Authorization header

Parameters:

Name In Type Required Description
providerUid path ProviderId ✅ Unique identifier of the provider

Request Body:

Content Type: application/json

Schema: PersonalAccessTokenExchange

Responses:

  • 200: Authentication validated

  • 400: Argument validation error

/auth/register/{providerUid}

POST

Register token

Register a new authentication for a provider by adding new cookie to the browser

Parameters:

Name In Type Required Description
providerUid path ProviderId ✅ Unique identifier of the provider

Request Body:

Content Type: application/json

Schema: PersonalAccessTokenExchange

Responses:

  • 200: Authentication registered

  • 400: Argument validation error

/auth/exchange/{providerUid}

POST

Exchange OAuth code

Exchange OAuth code for authentication object and register new cookie to the browser

Parameters:

Name In Type Required Description
providerUid path ProviderId ✅ Unique identifier of the provider

Request Body:

Content Type: application/json

Schema: OAuthCodeExchange

Responses:

  • 200: Authentication exchanged and cookie registered

  • 400: Argument validation error

/auth/refresh/{providerUid}

POST

Refresh OAuth token

Refresh OAuth access token and return new authentication object and new cookie to the browser

Parameters:

Name In Type Required Description
providerUid path ProviderId ✅ Unique identifier of the provider

Responses:

  • 200: OAuth access token refreshed

  • 400: Argument validation error

/auth/service-tokens/{resourceType}

PUT

Attach service token

Attach a service token to an account already signed in through the browser flow, replacing any token attached for the same resource type, and re-issue that account’s auth cookie. The account is designated by the X-Auth-Selector header. Programmatic clients pass service tokens to /auth/authorize/{providerUid} instead.

Request Body:

Content Type: application/json

Schema: ServiceTokenExchange

Responses:

  • 200: Service token attached and cookie re-issued

  • 400: Argument validation error

DELETE

Detach service token

Detach the service token of the given resource type from an account signed in through the browser flow, and re-issue that account’s auth cookie. The account is designated by the X-Auth-Selector header. Detaching a token that is not attached succeeds without change.

Responses:

  • 200: Service token detached and cookie re-issued

  • 400: Argument validation error

/auth/sign-out

POST

Remove authentication from cookie list

Remove authentication from browser cookies

Responses:

  • 200: Sign out successful

  • 400: Argument validation error

Schemas

AuthType

Type of the authentication

Type: enum

Values:

  • token
  • oauth

AuthAccessLevel

Access level of the authentication scope

Type: enum

Values:

  • readwrite
  • readonly

AuthDescriptor

Request authentication descriptor.

Type: object

Properties:

Name Type Required Description
accountKey AccountKey ✅
type AuthType ✅ Type of the authentication
accessLevel AuthAccessLevel ✅ Access level of the authentication scope
issuedAt number Unix time, in epoch seconds, when the auth was issued.
expiresAt number For OAuth, Unix time in epoch seconds when the underlying access token expires. Non-secret metadata the web application uses to decide whether a refresh is due.
refreshable boolean Whether the authentication can be refreshed (i.e. the underlying token carries a refresh token). Non-secret metadata the web application uses to offer a refresh action.
services array<ResourceType> Resource types that have a service token attached to this authentication. Non-secret metadata the web application uses to tell whether dedicated credentials (e.g. object storage keys) are still required.

AuthInfo

Descriptor of Auth to work in pair with cookies.

Type: object

Properties:

Name Type Required Description
descriptor AuthDescriptor ✅ Underlying auth descriptor
selector string ✅ Auth selector to be used in X-Auth-Selector header to pick auth from request’s cookie list.

AuthResponse

Response with authentication token to be used in subsequent requests in the Authorization header.

Composition: allOf

Type: object

Properties:

Name Type Required Description
signedAuth string ✅ Authentication token to be used in the Authorization header; usage: Authorization: Bearer <signedAuth>.

AuthInfoListResponse

Response with authentication descriptors to be used by web application

Composition: allOf

Type: object

Properties:

Name Type Required Description
auths array<AuthInfo> ✅ Authentication descriptors

OAuthCodeExchange

Request to exchange OAuth code for Authentication object

Type: object

Properties:

Name Type Required Description
code string ✅ OAuth code to exchange for Authentication object
accessLevel AuthAccessLevel Access level of the authentication scope. Defaults to readwrite when omitted.

PersonalAccessTokenExchange

Request to register a personal access token and get an Authentication object

Type: object

Properties:

Name Type Required Description
accessToken string ✅ Personal access token to register
accessLevel AuthAccessLevel Access level of the authentication scope. Defaults to readwrite when omitted.
serviceTokens object Optional service tokens to register together with the personal access token, keyed by resource type (e.g. bucket). Only types for which the provider’s static data reports customCredentials: true are accepted.

ServiceTokenExchange

Credentials for a provider service that does not accept the account’s main API credentials, such as S3-compatible object storage.

Type: object

Properties:

Name Type Required Description
accessToken string ✅ Service credentials. A key pair, such as an S3 access key, is given as <accessKeyId>/<secretAccessKey>.
Last updated October 30, 2026Send feedback