Is there a FastNode CLI?

No first-party CLI exists today. Use the HTTP API with curl, your language's HTTP client, or a small wrapper script of your own. We will not advertise a CLI until one ships.

Where is the endpoint reference?

In the portal, alongside the API keys page. It is the source of truth for paths, parameters and scopes, and it changes with the platform, so we don't copy it onto this marketing site.

Can I see a key again after creating it?

No. The full key is shown exactly once, at creation. Afterwards the portal only shows its prefix and metadata. If you lose it, revoke it and create a new one.

How should I limit what a key can do?

Give each key the narrowest scopes its job needs, one key per system, and an expiry where the portal allows it. A CI job that only reads server status should not hold a key that can reinstall machines.

API Keys and Webhooks for Automation

What you get

Two primitives, both managed under your account in the portal:

API keys: bearer tokens tied to your account, each with its own set of scopes. Create as many as you need, name them, revoke them individually.
Webhooks: HTTPS callbacks we send to a URL you control when things happen on your account, so your systems react to events instead of polling.

There's no SDK to vendor and no CLI to pin. Anything that can make an HTTPS request can use it.

How keys behave

Property	Behaviour
Visibility	Full value shown once, at creation. After that, prefix and metadata only.
Scope	Each key carries explicit scopes. A request outside them is refused.
Account boundary	A key acts for your account only. It can't see anyone else's resources.
Metadata	Portal shows name, prefix, scopes, created time, last-used time and last-used IP.
Revocation	Revoke from the portal; the key stops working for new requests.

The last-used IP column is more useful than it looks. If a key labelled "ci-runner" was last used from an address that isn't your runner, revoke it first and investigate second.

Calling the API

Send the key as a bearer token over HTTPS. The pattern, with the path left as a placeholder because the reference in the portal is authoritative:

export FASTNODE_TOKEN="$(cat ~/.config/fastnode/token)"   # never inline it
curl -fsS \
  -H "Authorization: Bearer ${FASTNODE_TOKEN}" \
  -H "Accept: application/json" \
  "https://portal.fastnode.uk/<path-from-portal-reference>"

-f makes curl exit non-zero on HTTP errors, which is what you want inside scripts and CI steps. Without it, a 401 looks like success to your shell.

Storing keys properly

An API key is a password that never expires unless you make it. Treat it that way.

Never commit it. Not in .env, not in a "temporary" test script. Add a secret scanner to pre-commit or CI if your team doesn't have one.
One key per system. Separate keys for CI, for your laptop and for the monitoring box. Revoking one doesn't break the others.
Least scope. Read-only where read-only will do.
File permissions. On a workstation, chmod 600 the token file and keep it outside the repository.
Rotate on departure. When someone with access leaves, rotate the keys they could read. The created-time column tells you which ones are old.

install -d -m 700 ~/.config/fastnode
printf '%s' 'PASTE-ONCE' > ~/.config/fastnode/token
chmod 600 ~/.config/fastnode/token

Using keys from CI

Put the key in your CI system's secret store, expose it to only the jobs that need it, and mask it in logs. Every mainstream CI platform has a protected-variable or secrets feature; use it rather than an environment file baked into the runner image.

# generic CI step
- name: Check target server state
  # FASTNODE_TOKEN injected from the CI secret store, masked in logs
  run: ./scripts/fastnode-status.sh

Restrict secrets to protected branches where your platform allows it. A pull request from a fork should never be able to print your production key. If you run your own runners on FastNode servers, see CI runners for isolation advice, and the deploy pipeline guide for a full push-to-deploy flow.

Webhooks

Register an HTTPS endpoint in the portal and we'll POST to it when events occur on your account. The event types available are listed in the portal next to the webhook form. Use them to post to a team chat channel, open an internal ticket, or kick off a job.

Build your receiver defensively:

HTTPS only, with a valid certificate.
Verify authenticity using whatever signing or secret mechanism the portal provides for your webhook, and reject anything that fails.
Respond fast. Return 2xx as soon as you've stored the payload; do the slow work in a queue.
Be idempotent. Assume an event can arrive more than once and key your processing on its identifier.
Log raw bodies for a short window so you can replay when your handler had a bug.

# minimal receiver shape (Python, any framework)
@app.post("/hooks/fastnode")
def hook(request):
    body = request.body
    if not verify(request.headers, body):   # per the portal's scheme
        return 401
    queue.put(body)
    return 204

Rate and retry etiquette

Write clients that back off. On a 429 or a 5xx, wait and retry with exponential delay and jitter; on a 4xx other than 429, stop and fix the request. Cache read results that don't change often instead of asking every minute. Polite clients keep working when the platform is busy.

Where to go next

Open the portal, create a read-only key, and make one authenticated request from your terminal. Then build out from there. The platform page lists what the portal itself controls; the API backends page covers hosting and protecting your own endpoints.

API keys and webhooks