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
61 lines
2.4 KiB
Markdown
61 lines
2.4 KiB
Markdown
---
|
|
layout: default
|
|
title: API Tokens
|
|
description: 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](api.html).
|
|
|
|
## 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](concepts-access.html)
|
|
— 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](api.html).
|
|
|
|
[← Back to Home](index.html)
|