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

# Quickstart

> Pick your integration path and set up API access in under five minutes.

## Integration Paths

<CardGroup cols={2}>
  <Card title="Hosted Components" icon="window" href="/guides/hosted-checkout">
    Send customers to a branded, Nomos-hosted checkout and customer portal. No
    frontend code required.
  </Card>

  <Card title="Build your own" icon="terminal" href="/guides/checkout">
    Quote pricing, collect customer info, and create a subscription against the
    API end-to-end.
  </Card>
</CardGroup>

## Make your first authenticated request

<Steps>
  <Step title="Get an access token">
    The Nomos API uses OAuth 2.0. This quickstart uses the client credentials
    grant for server-to-server requests; for third-party integrations acting on
    behalf of a customer, see [Authentication](/api-references/authentication).

    Create a `client_id` and `client_secret` in the [Nomos
    dashboard](https://dashboard.nomos.energy). If you don't have dashboard
    access yet, ask your dedicated Nomos contact.

    Exchange your credentials for a short-lived access token:

    <CodeGroup>
      ```bash cURL theme={null}
      curl -X POST https://api.nomos.energy/oauth/token \
        -u "${CLIENT_ID}:${CLIENT_SECRET}" \
        -d grant_type=client_credentials
      ```

      ```ts Node.js theme={null}
      const credentials = Buffer.from(
        `${process.env.CLIENT_ID}:${process.env.CLIENT_SECRET}`,
      ).toString("base64");

      const res = await fetch("https://api.nomos.energy/oauth/token", {
        method: "POST",
        headers: {
          Authorization: `Basic ${credentials}`,
          "Content-Type": "application/x-www-form-urlencoded",
        },
        body: "grant_type=client_credentials",
      });

      const { access_token } = await res.json();
      ```

      ```python Python theme={null}
      import os, requests

      res = requests.post(
          "https://api.nomos.energy/oauth/token",
          auth=(os.environ["CLIENT_ID"], os.environ["CLIENT_SECRET"]),
          data={"grant_type": "client_credentials"},
      )
      res.raise_for_status()
      token = res.json()["access_token"]
      ```
    </CodeGroup>

    The access token is valid for 60 minutes. Cache it; when it expires,
    [refresh it](/api-references/authentication#token-lifecycle) instead of
    asking for a new one.
  </Step>

  <Step title="Make a request">
    List the plans configured on your organization. This proves your token
    works.

    <CodeGroup>
      ```bash cURL theme={null}
      curl https://api.nomos.energy/plans \
        -H "Authorization: Bearer ${ACCESS_TOKEN}"
      ```

      ```ts Node.js theme={null}
      const res = await fetch("https://api.nomos.energy/plans", {
        headers: { Authorization: `Bearer ${access_token}` },
      });

      const { items } = await res.json();
      ```

      ```python Python theme={null}
      res = requests.get(
          "https://api.nomos.energy/plans",
          headers={"Authorization": f"Bearer {token}"},
      )
      res.raise_for_status()
      items = res.json()["items"]
      ```
    </CodeGroup>

    If you see an `UNAUTHORIZED` error, your token is missing, malformed, or
    expired. See [Errors](/api-references/errors).
  </Step>
</Steps>