> For the complete documentation index, see [llms.txt](https://stablebuild.gitbook.io/en/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://stablebuild.gitbook.io/en/product/public-api-keys.md).

# Public API keys

A public API key lets you use StableBuild in an open-source project. You publish the key in your Dockerfile or CI configuration, and anyone who builds your project pulls the same pinned dependencies through StableBuild. The key only serves the dependencies you allowed, so the rest of your organization's dependencies stay private.

{% hint style="warning" %}
All traffic through a public key is billed to your organization. On the Community plan, the monthly traffic limit of your organization still applies, so builds through the public key fail once the cap is reached.
{% endhint %}

### How it works

A public key is read-only. It only serves files that are on its allow-list and already cached by StableBuild, and it never downloads anything new from upstream.

To fill the allow-list, you open a write window on the key. While the window is open, the key works like a regular API key, and everything it serves is added to its allow-list. Run your build once, then close the window.

{% hint style="info" %}
While a write window is open, anyone with the key can pull anything through it. Keep the window short, and close it as soon as your build has finished.
{% endhint %}

### Creating a public key

1. Go to the [dashboard](https://dashboard.stablebuild.com) and click **Keys > Add new key**.
2. Enter a name, and check **Public key**. The key now starts with `your-prefix-pub-`.
3. Click **Add key**. The **Open write window** dialog opens right away, so you can go on with [recording your dependencies](#recording-your-dependencies).

Public keys are marked **Public** in the list of keys, with **Read-only** or **Writable until** next to it.

### Recording your dependencies

1. On the **Keys** page, click the three dots next to your public key, then **Open write window**. If you just created the key, this dialog is already open.
2. Copy the key with the button next to it, choose when the window closes automatically (after 1 hour, 24 hours or 7 days), and click **Open write window**.
3. Run your build once with the public key, for example:

{% code overflow="wrap" %}

```docker
FROM your-prefix-pub-myproject.dockermirror.stablebuild.com/python:3.12-slim

ARG SB_API_KEY=your-prefix-pub-myproject
ARG APT_PIN_DATE=2026-09-29T08:40:01Z

COPY ./sb-apt.sh /opt/sb-apt.sh
RUN bash /opt/sb-apt.sh load-apt-sources debian
RUN apt update && apt install -y curl

RUN pip install -i https://your-prefix-pub-myproject.pypimirror.stablebuild.com/2026-09-01/ requests==2.32.3

RUN curl -O "https://your-prefix-pub-myproject.httpcache.stablebuild.com/my-cache-key/https://bootstrap.pypa.io/get-pip.py"
```

{% endcode %}

4. Click the three dots next to the key again, then **Close write window**.

Anyone can now build your project with this key. When your dependencies change, open a new write window and run the build again.

### Managing the allow-list

To see what a public key can download, click the three dots next to the key, then **Allowed items**. Items are grouped by mirror, with the date they were added. Click **Remove** to take an item off the allow-list.

After closing a write window or removing an item, it might take 5 minutes for the key to become read-only or stop serving the item.

To see who uses your public key, go to **Billing > Raw usage logs**. Every request lists the API key it was made with.