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