Authentication

There are two ways to authenticate, and which one you want depends on whether a human is present. Automation carries a workspace token. A person at a terminal signs in through the browser.

Workspace tokens

A workspace token is minted in the app — Settings → API keys — and looks like amolfi_sk_…. It is shown once, at mint time. Amolfi stores only its hash, so nobody, including Amolfi, can read it back to you later. Lose it and you mint a new one.

The token names its workspace inside itself, so there is no workspace header to set and nothing in a request can widen its reach. One token, one workspace.

Authorization: Bearer amolfi_sk_…

A token is a delegation, not a new identity

Every request is checked against the live permissions of the member who minted the token, re-resolved on each call. Narrow that person’s access and the token narrows with it on the very next request. Revoke the token, or deactivate the member, and it stops working immediately.

Scopes are the second gate. A token carries scopes from the public catalog, and the effective authority of any call is the intersection of the token’s scopes, the minter’s live permissions, and the tool’s own permission requirement. Read /v1/scopes to see the whole table before you mint anything.

Signing in from a terminal

For a person, pasting a long-lived secret into a shell is the wrong shape. amolfi login runs the OAuth 2.1 Device Authorization Grant (RFC 8628) instead: the terminal shows a URL and a short code, you approve in a browser where you are already signed in, and you pick the workspace there rather than in the terminal.

POST /v1/auth/device/code    → device_code, user_code, verification_uri_complete, interval, expires_in

  # the browser opens amolfi.com/activate, you confirm the code and pick a workspace

POST /v1/auth/device/token   → 428 authorization_pending  (keep polling)
                             → 429 slow_down             (poll slower)
                             → 200 access_token, refresh_token, org_id, scopes

Both device routes are form-encoded (application/x-www-form-urlencoded), as RFC 8628 requires — a JSON body is refused. Poll no faster than the interval the server returns, and back off when it says to.

Sign-in returns a short-lived access credential — under an hour — plus a rotating refresh credential. Refreshing consumes the old one; reusing a spent refresh credential revokes the whole grant, because reuse is what a stolen credential looks like. The grant is also bound to the permissions you held when you approved it: change them and the grant closes rather than quietly widening.

Which one to use

Workspace token — n8n, CI, cron, anything unattended. Export it as AMOLFI_TOKEN.
Device sign-in — a person working in a terminal. Run amolfi login.
Neither — /v1/health, /v1/scopes, and /v1/openapi.json need no credential at all.

Open API keys The CLI