wmantly
426fa111ec
- New docs/concepts-{hosts,dns,access,api-tokens}.md -- plain-language
guides aimed at less technical readers, each linking onward to the
existing system-design-level doc for anyone who wants that detail.
Card help links (Proxy List, Add/Edit host, DNS Provider cards,
Users/Permissions/Groups cards) now point here instead of straight at
Installation/Architecture.
- The "New API Token" card had no help link at all -- added, pointing to
the new API Tokens doc.
- Fixed the in-app docs viewer rendering every docs/*.md page with a
garbled heading + stray <hr> at the top: Jekyll front matter (meant
only for the GitHub Pages build) was never stripped before being
handed to the markdown renderer.
- Fixed cross-doc links never resolving in-app, since this viewer serves
docs at /docs/<slug> with no .html suffix: rewritten to the correct
in-app URL, first by registered slug, falling back to the doc's real
filename (the correct, working link form on the Jekyll/GitHub Pages
build) -- same idea as the existing image-path fix, and lets one link
written in a doc work on both targets.
Bumps to v1.1.13.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KDEx8ghuZR61pqPXc6da9C
2.4 KiB
layout, title, description
| layout | title | description |
|---|---|---|
| default | API Tokens | A plain-language guide to personal access tokens in theta42/proxy. |
API Tokens
This page explains what an API token is and when you'd want one. For the full list of API endpoints a token can call, see the API reference.
What's an API token, in plain terms?
Normally, you interact with this app by logging in through a web browser. An API token (also called a personal access token, or PAT) is an alternative way in — a long, random string that a script, a scheduled job, or another program can use instead of a username and password, to act on your behalf without a human typing a login in each time.
If you've ever set up a script to talk to GitHub, GitLab, or a similar service using a "token" instead of your real password, this is the same idea.
When would you actually need one?
Most people never need to create one of these — you'll only want a token if you're automating something, for example:
- A script that registers or updates hosts automatically (say, spinning up a new service and wanting the proxy entry created for it without a manual step).
- A monitoring or backup job that checks this app's health via its API.
- A configuration-management tool that keeps your host list in sync with something else.
If you're not doing any of that, you don't need an API token — just log in normally through the web UI.
How it works
Create a token from your Profile page, give it a name so you remember what it's for later, and optionally an expiry. You'll be shown the token's value exactly once — copy it somewhere safe immediately, because it can't be viewed again afterward (only revoked or rotated). Whatever script or tool you're using it with sends it along with each request, the same way a browser sends your login session.
A token acts as you, with your permissions — if you're only a Manager on one domain, a token you create can't touch any other domain either. If you ever suspect a token has leaked (ended up somewhere it shouldn't have, like a public script or log file), revoke it immediately from your Profile page; it stops working right away.
Want more detail?
This page doesn't attempt to list every API endpoint or show request/ response examples — for that, see the full API reference.