# Quickstart

Create a scoped key and make your first authenticated request.

Updated: 2026-10-02

## 1. Create an API key

Sign in, select your workspace, and open Dashboard → Developer access. Owners and admins can create keys. Start with sites.read and bind the key to one website if that is all your integration needs. Copy the token once and store it in your agent's secret store or server environment.

> Keys expire in 1–90 days; the default is 30. The token is shown only at creation. If lost, revoke it and create another.

## 2. List your websites

```bash
curl "https://buildasite.ai/api/v1/sites?limit=30" \
  -H "Authorization: Bearer $BUILDASITE_API_KEY"
```

Read nextCursor from the response and pass it as after to fetch the next page. Site-bound keys return only their website.

## 3. Use the API library

Download /sdk/buildasite.mjs and /sdk/buildasite.d.mts into your server project. This dependency-free library provides a named method for every external operation and throws BuildASiteError with status, code, and retryAfter.

```javascript
import { BuildASite } from "./buildasite.mjs";
const client = new BuildASite({ token: process.env.BUILDASITE_API_KEY });
const { sites } = await client.list_sites({ limit: 30 });
const site = await client.get_site({ siteId: sites[0].id });
console.log(site.version);
```

> Keep API keys out of browser bundles, public repositories, screenshots, and logs. Examples use environment variable names, never real credentials.