> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.kuudo.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.kuudo.com/_mcp/server.

# Quickstart

> Exchange an API key and make your first authenticated request.

## 1. Create credentials

In Kuudo's developer dashboard, create an M2M client for the organization you want
to access. Select `servers:read`, then create an API key linked to that client.
Copy the key when it is shown; it is displayed only once.

Keep the key in your application's secret store. Run these requests from your
backend or a trusted development shell.

## 2. Exchange the key

Set `KUUDO_API_KEY` securely in your shell, then run:

```bash
curl --fail-with-body --request POST \
  https://app.kuudo.com/api/auth/token-exchange \
  --header "Authorization: Bearer ${KUUDO_API_KEY}"
```

The response includes:

```json
{
  "access_token": "<access_token>",
  "token_type": "Bearer",
  "expires_in": 900,
  "scope": "servers:read",
  "organization_id": "org_example",
  "client_id": "m2m_example",
  "plan": "pro"
}
```

The token lifetime depends on the M2M client and ranges from 300 to 900 seconds.
Use the returned `expires_in`. Cache the JWT securely and exchange again before it
expires; these tokens do not have a refresh-token flow.

## 3. List servers

Store the returned JWT as `KUUDO_ACCESS_TOKEN` and call:

```bash
curl --fail-with-body \
  https://app.kuudo.com/api/servers \
  --header "Authorization: Bearer ${KUUDO_ACCESS_TOKEN}"
```

The response has a `servers` array, sorted oldest first. An organization without
servers receives:

```json
{ "servers": [] }
```

If a request returns `403` with `insufficient_scope`, verify that your client has
every scope required by the endpoint, then exchange its key again to obtain a
token with the updated scope list.