Skip to content
Kapten
Esc
↑↓navigate↵open⌘Jpreview
On this page

API overview

Call the Kapten Platform and Auth APIs from scripts and CI with an OAuth application's access token.

Everything the console does goes through two HTTP APIs, which you can call from your own scripts and CI.

API Base URL What it manages
Platform API https://api.kapten.io Projects, environments, applications, jobs, databases, pipelines, clusters, variables and secrets
Auth API https://auth.kapten.io Organizations, members, invitations, Roles, OAuth applications, single sign-on and billing

Both take and return JSON, and every request needs an access token.

Authentication

A script authenticates as an OAuth application: a machine client of your organization, with its own Roles. It exchanges its credentials for a short-lived access token with the OAuth 2.0 client credentials grant, then sends that token with every request.

Create an OAuth application

In the Kapten console, open Settings, then OAuth applications, and create an application with a client secret. Give it only the Roles the script needs: its tokens can do what those Roles allow, in your organization only.

Copy the client ID and the secret. The secret is shown once.

Get an access token

curl -s https://auth.kapten.io/token \
  -u "$KAPTEN_CLIENT_ID:$KAPTEN_CLIENT_SECRET" \
  -d grant_type=client_credentials

The response holds the token in access_token, and its lifetime in seconds in expires_in. Request a new one when it expires: the client credentials grant has no refresh token.

Call the API

Send the token in the Authorization header:

curl -s https://api.kapten.io/project \
  -H "Authorization: Bearer $KAPTEN_TOKEN"

The token endpoint also accepts the client ID and secret as client_id and client_secret form fields, and a signed JWT assertion (private_key_jwt) in place of a secret, for applications you register a public key for. The authorization server’s discovery document lists the endpoints and methods it supports.

Errors

A request without a valid token gets 401 Unauthorized. A token whose Roles do not allow the operation gets 403 Forbidden. Each operation page lists the responses it can return and their bodies.

Was this page helpful?