---
title: API overview
description: Call the Kapten Platform and Auth APIs from scripts and CI with an OAuth application's access token.
sidebar:
  label: Overview
---

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](/api/platform) | `https://api.kapten.io` | Projects, environments, applications, jobs, databases, pipelines, clusters, variables and secrets |
| [Auth API](/api/auth) | `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.

1. **Create an OAuth application**

    In the [Kapten console](https://app.kapten.io), 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.

2. **Get an access token**

    ```bash
    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.

3. **Call the API**

    Send the token in the `Authorization` header:

    ```bash
    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](/api/auth/oauth/get-openid-configuration) 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.
