Quickstart

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:

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

The response includes:

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

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:

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:

{ "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.