Skip to main content

Headless authentication

This guide is the path for headless, unattended callers — CI pipelines, agents, backend services, cron jobs, and scripts that run with no human present. These callers can't open a browser to sign in, so they authenticate with a long-lived org-level service-account API key instead.

info

Headless, unattended automation requires the API plan. Service-account sk_ keys are only issued to organizations on the plan — see API plan for what it unlocks and how to turn it on.

Machine credentials vs. human sign-in​

Slothbox draws a clean line between credentials meant for machines and the interactive sign-in meant for people:

  • Service-account sk_ keys are for machines. They are long-lived — valid until you revoke them — which is exactly what an unattended process needs: there is no browser to redirect to and no token to refresh. This is what you reach for in CI, in an agent loop, or in a backend service.
  • OAuth sign-in is for humans. When a person is driving, they sign in interactively instead: the web app, the CLI (slothbox login, see Signing in), and the MCP server's browser-consent flow (see MCP server) all run an OAuth flow and hand back a session token. Those sessions are short-lived and TTL-scoped — they expire on a fixed window and are refreshed silently — so they are unsuitable for anything that runs on its own.

The rule of thumb: if a person is at the keyboard, let them sign in; if a process is running on its own, give it a service-account key. The two credential types and how the Authorization header works are described in full on Authentication.

1. Create an org-level service-account key​

Service-account keys belong to the organization, not to any one person, so they are minted by an organization owner in the web app under the org's Service accounts settings. Make sure your organization is on the API plan first — owners can only mint service-account keys once it's on.

The key is shown once, at creation time. Copy it immediately; if you lose it, revoke it and mint a new one.

2. Store the key as a CI / agent secret​

Never commit the key or bake it into an image. Put it in the secret store of whatever runs your automation — your CI provider's encrypted secrets, your agent platform's secret manager, or your backend's configuration store — and read it from there at run time. Because the key is long-lived, it stays valid across runs until you choose to revoke it.

3. Send it in the Authorization header​

Send the key verbatim in the Authorization header, with no Bearer prefix — the same way every Slothbox credential is presented:

Authorization: sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Here is a runnable check against /me, identical in shape to the call in Quickstart — substitute your service-account key for the placeholder:

curl https://api.slothbox.dev/me \
  -H "Authorization: sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

You should get back a JSON document with the identity the key resolves to and the organization it belongs to. From a script reading the key out of a secret, the same call looks like:

curl https://api.slothbox.dev/me \
  -H "Authorization: $SLOTHBOX_API_KEY"

Once /me succeeds, your automation can call any endpoint the key is allowed to reach — the full set is in the API reference.

Throughput and limits​

Service-account keys run at the API plan's higher rate tier, suited to automation at scale rather than the light, occasional scripting a personal seat key is meant for. How per-caller limits work and how to back off on a 429 are covered in Rate limiting.

Next steps​