Authentication
Almost every novem endpoint needs a bearer token. This page covers how you get one, how to manage your tokens, and the handful of public endpoints that don't require auth.
AI assisted, human approved — novem uses AI to review and keep our documentation up to date.
The novem API authenticates with a bearer token. You send it on every
request as an Authorization: Bearer <token> header (the CLI and python
library do this for you once you've logged in). A few endpoints (registration,
login, and the e-mail challenge) are public, so you can bootstrap an account and
a token in the first place.
Every path below also answers OPTIONS with the verbs valid for your token.
| Verb | Path | Auth | Description |
|---|---|---|---|
POST | /v1/register | public | Register a new user account |
POST | /v1/auth | basic | Log in with username + password; creates a token and sets a session cookie |
POST | /v1/token | basic | Create a new named API token; the token value is returned in the response |
GET | /v1/token | token | Verify credentials; returns 200 if the token is valid |
POST | /v1/logout | token | Invalidate the current session |
Note: the token value is shown once, when it's created. Store it
somewhere safe. You can't read it back later, only revoke it and issue a new
one. The CLI keeps it for you in ~/.config/novem/novem.conf.
Some flows (registering, or verifying an e-mail address) send a code or link to your inbox and ask you to prove you received it.
| Verb | Path | Auth | Description |
|---|---|---|---|
POST | /v1/admin/challenge | public | Answer a challenge by its uid (knowing the uid from the e-mail is the proof, so no token is required) |
| Verb | Path | Description |
|---|---|---|
GET | /v1/whoami | The user the current token authenticates as; useful for confirming which account a token belongs to |
Your active tokens live under /v1/admin/tokens, addressed by name. This is
where you audit and revoke them, for instance to roll a token that may have
leaked or to clean up ones you no longer use.
| Verb | Path | Description |
|---|---|---|
GET | /v1/admin/tokens | List your tokens |
GET | /v1/admin/tokens/:token | A token's folder |
GET | /v1/admin/tokens/:token/info | Token metadata: name, creation time, last use |
GET | /v1/admin/tokens/:token/log | That token's activity log |
DELETE | /v1/admin/tokens/:token | Revoke the token |
- API overview — the request shape, verbs and permissions.
- Terminology — usernames, FQNPs and shortnames.
- Profile — your account's identity and settings.