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

# Driving docks from your own software

> The Integration page: the sandbox/production snippet, picking a dock and a key, and how API keys work — who can see them, what they reach, and how to rotate one.

Everything the dashboard does to a dock, your own code can do over HTTP. The **Integration** page
has what you need to start.

A slider in the snippet's header switches between two targets, and the sample updates completely —
base URL and dock id both, because the two environments share neither. The **sandbox** drives deterministic
fake hardware: one practice dock, `sandbox-dock`, whose outcome you choose per request with the
`Sandbox-Behavior` header, so you can exercise a success, an obstruction and a timeout
without touching a real door. **Production** is your actual fleet. Both speak the same paths, the
same request and response shapes, and the same error codes, and both take the same key. Only the
base URL and the dock id change.

The snippet is filled in with your own values in TypeScript, Python, Go, or as a `curl` command.
It is meant to be pasted, not translated. Until you pick a key it reads `OUTPOST_API_KEY` from the
environment, which is the habit you want anyway.

**Click a key's box in the table** and two things happen: the full secret goes to your clipboard,
and the snippet below switches to that key. Click a different one and the snippet follows, so the
code on screen is always the credential you last took.

The **dock callsign** in the snippet — the two-word name like `earnest-petrel` — is underlined with
dashes because it is a picker. Click it to choose which dock the sample commands; the list shows each
dock's name with its callsign in parentheses. The callsign is the dock's real identifier and works
anywhere the API asks for a dock, so a snippet built this way is one you can keep.

The page does not scroll. The key table and the snippet scroll inside themselves, so opening the
snippet shrinks the table to a couple of rows and closing it gives the space back. Collapse it and
it stays collapsed next time you visit.

## API keys

A key is how your software proves who it is.

Keys belong to your organization, not to you personally, but they are **admin-only**: only an
owner or admin of your organization can see the list, copy a secret, create a key, rename one or delete one. A key is a
standing grant that opens a physical door, so anyone holding the secret can move your hardware
whatever their role says. If you are an Operator or a viewer, the Integration page does not appear for you —
ask an owner or admin to create a key and send your software what it needs.

Creating one asks for a **name** and an **expiry**. Name it after the thing that will use it: a key
called "CI deploy" tells the next person what breaks if they delete it. Expiry runs from a week to a
year, or no expiry at all; the default is 90 days, and a short one is the cheapest protection you
have against a key that leaks without anyone noticing.

The key reaches every dock your organization owns, including ones you add later, and may open and
close them.

The row menu (**⋮**) renames a key or deletes it. Renaming is safe — it changes the label, not the
credential, so nothing using the key notices. There is no way to widen or narrow an existing key,
which is deliberate: that would change what the key can do without changing the key itself, and
anything already holding it would silently gain reach. Create a new key and delete the old one.

<Note>
  The API itself accepts narrower keys — a specific list of docks, or open-only — and enforces those
  limits on every command. The dashboard does not offer the choice because in practice every key is
  used fleet-wide, and there is no published way to mint one today: key management is not part of
  the public API, and the dashboard's form is the only surface that creates keys.
</Note>

The copy button beside a key fetches the full secret and puts it on your clipboard; an admin can do
that again any time, so there's no moment where losing it costs you the key. If a key is compromised, delete it and mint another — that takes effect
immediately.

## If you tried the sandbox before signing up

You can get a sandbox key with no account at all, which is how the published quickstart starts.
That key expires 24 hours after it was minted and can never reach your real docks. It is not the
same key your organization will use, and there is no way to upgrade it: once you have an
organization, an owner or admin creates a proper key from the Integration page with **Create API
key**, and your software switches to that. The page does not prompt you — a new organization simply
starts with an empty key table under that button.


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