> ## Documentation Index
> Fetch the complete documentation index at: https://docs.internal.nscale.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Overview

> Integrate with the Fleet Manager API from agents, CLIs, and external services.

Any non-browser client — Fleet Manager's own internal agents, `fleetctl`, CI harnesses, dashboards, external services — talks to the Fleet Manager API through one auth model: **OAuth 2.0 client-credentials with short-lived bearer tokens**. Identity is proven one of two ways: FM's own agents and SDK consumers sign a JWT with a private key whose certificate chain is trusted by the API; external services hold a plain client secret instead.

## Three kinds of clients

The token endpoint is the same for all of them, but the credential and the setup workflow differ. Pick the row that matches what you're building:

| Your situation | Start here |
| - | - |
| Building a new **Fleet Manager data-sync agent** — a pod that pulls from a source system, caches it, and reconciles into a target. This is a specific FM-internal code pattern (`ListReflector` / `Store` / `Controller` / reconciler). | [Build a New Agent](../authoring-guides/build-a-new-agent) for code layout, then [Client Authentication](./client-authentication#in-cluster-agents-the-standard-path) for cert wiring. |
| Building a **dashboard, CLI, or CI script** that uses the FM Python SDK. You don't need the FM agent code patterns; you just need to authenticate. | [Client Authentication → External clients](./client-authentication#external-clients-dashboards-ci-services-outside-the-fm-cluster) — the certificate + SDK recipe. |
| Building an **external service** — another product's backend, any language, no FM SDK or PKI access. | [Client Authentication → External services: client secret](./client-authentication#external-services-client-secret). Don't build JWT assertion signing. |
| Just trying to understand how an existing endpoint is gated. | [Scopes and Permissions](./scopes-and-permissions). |

If your client runs on your laptop, in CI, or in any cluster other than Fleet Manager's own — you're in the second or third row. The "agent" pattern in row 1 is a specific FM-internal code shape, not a generic word for "API client."

## Glossary (the words this section uses without defining them)

* **Hub cluster** — the central Kubernetes cluster that runs the Fleet Manager API and hub-side agents (e.g. `netbox-agent`).
* **Satellite cluster** — a per-site Kubernetes cluster that runs site-local agents (`workflow-agent`, `openstack-agent`, `slurm-agent`). Each site has its own.
* **`cert-manager`** — the in-cluster controller that issues and rotates leaf certificates from a configured CA. In Fleet Manager, every agent pod gets its leaf cert this way.

## Environments

| Environment | API URL | Where the CA chain lives |
| - | - | - |
| Local Docker Compose | `http://localhost:8000` (host) / `http://fm-api:8000` (in-network) | `fm_certs` Docker volume — populated by `fm-generate-certs` |
| Dev cluster | `https://api.fleet.dev.nscale.com` | Hub root CA in [1Password](../../start-here/glossary#1password) vault `Fleet Manager hub dev`; `cert-manager` issues leaves in-cluster |
| Production | `https://api.fleet.nscale.com` | Hub root CA in 1Password vault `Fleet Manager hub prod`; `cert-manager` issues leaves in-cluster |

The 1Password vaults hold the **root CA** that signs agent certs. Per-client credentials, where they exist, live as separate items in the same vault (convention: `<client-name>-creds`, with `cert` and `key` fields) — see [Client Authentication → External clients](./client-authentication#external-clients-dashboards-ci-services-outside-the-fm-cluster) for the canonical pattern.

## The two deeper pages

* [Client Authentication](./client-authentication) — which of the two credential mechanisms applies to you, how `ensureagentclient` registers a client, where the cert comes from in each environment, and the concrete recipes for external clients and external services. Ties into the PKI tree at [PKI and Certificate Trust](../../deployment-guide/pki-and-certificate-trust).
* [Scopes and Permissions](./scopes-and-permissions) — the `resource:action` grammar, how endpoints derive their required scope automatically, and what to update when you add a new model.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.