Admin Tour

A walk through the AstroBaaS admin at /admin, screen by screen, in the order the sidebar shows them. It is for operators and editors who want to know what each screen is for and which roles can reach it.

The sidebar is defined as data in src/lib/admin-nav.ts, and who may open each screen is decided in one place, src/lib/admin-access.ts. The middleware, the sidebar and the command palette all ask the same function, so a link is never shown to someone who would be refused when they click it.

Roles

AstroBaaS has five fixed roles. Custom role names are not supported. An admin can adjust what the four non-admin roles are allowed to do (see Users under System).

Role	Meant for	Can open the admin?
admin	The site owner. Everything.	Yes, every screen
editor	Editorial staff. Writes and publishes anyone's content, manages the catalogue.	Yes
author	A writer. Writes their own posts and uploads media.	Yes
manager	Shop staff. Runs the catalogue, can read orders and customers.	Yes
viewer	Read-only accounts, mostly used for API keys.	No

Built-in capabilities

These are the default grants from src/lib/capabilities.ts. The admin role always has all of them.

Capability	What it allows	editor	author	manager	viewer
author_posts	Write posts and upload media	yes	yes	yes	no
manage_all_posts	Edit and delete anybody's posts (and media)	yes	no	no	no
import_content	Run a content import	no	no	no	no
manage_catalog	Create and edit products	yes	no	yes	no
delete_products	Delete products	no	no	yes	no
read_commerce	See orders and customers	yes	no	yes	no
write_commerce	Change orders and customer records	yes	no	no	no
override_tax	Override the VAT on an order, with a recorded reason	yes	no	yes	no

Two rules are not in that table:

• Publishing. Only admins and editors can publish when the site holds posts for review (Settings → Reading → "Hold posts for review before they go live"). Authors and managers then set a post to review. This is a setting, not a capability.
• Refunds are admin only.

Which screens each role can open

Screen	admin	editor	author	manager
Dashboard, Posts, Categories, Media, Translations, Profile	yes	yes	yes	yes
Products	yes	yes	no	yes
Orders, Customers	yes	no	no	yes (read-only)
Redirects, Insights	yes	yes	no	yes
Custom collections (/admin/content/<type>)	yes	yes	no	no
Everything else (Messages, Import, Content types, Themes, Legal pages, Users, Plugins, API keys, Webhooks, Background jobs, Email wording, Data requests, Audit log, Tools, Settings)	yes	no	no	no

Any admin path without a rule is treated as admin only. Plugin screens under /admin/plugin/<id>/ follow the roles the plugin declares, and are admin only if it declares none.

Editors have read_commerce but the Orders and Customers screens are not in their list. They can still reach that data through the API.

The shell

Header

The top bar has the command palette button, a View site link, and the account menu (Profile, Sign out).

Command palette

Press Ctrl K (or Cmd K on a Mac), or click "Search and jump to…". It lists every screen the sidebar shows you, including your custom collections and plugin pages, grouped the same way. Matching ignores accents, case and the Greek final sigma. Recent jumps appear at the top.

The list is built on the server from your role, so the palette never shows a screen you cannot open. For now it only searches screens. It does not search products, orders or posts by name. Source: src/components/admin/CommandPalette.astro.

Attention feed

The dashboard opens with What needs your attention, sorted into "Needs fixing", "Unfinished" and "Worth knowing". Each card links to the screen where you can fix it. The checks include:

Check	What it means
Site URL unset	Canonical links, the sitemap and email links are guessed from the request host
Tax origin unset	Tax is on but the shop has no origin country
Schema behind	The database schema is older than this build expects (a migration probably failed)
Flagged orders	Orders the risk signals flagged for a human look
Listed but out of stock	Active products nobody can buy
Overdue scheduled posts	Scheduled posts whose date has passed but which never published
Brand spellings	Brands whose spelling needs a decision
AI assistant error	The configured AI provider last returned an error
Orders need refund	Payment arrived after the order was cancelled
Payment return URLs	Card, PayPal or Klarna buyers would come back to a page that does not exist

The header also has a bell icon, but it does nothing yet. The attention feed on the dashboard is where these alerts appear.

Dashboard

/admin. Shows the attention feed, a warning if the default admin account still has its original password, and summary numbers. With commerce on, those numbers are open orders, paid revenue, products and out-of-stock items. The blog numbers are total, published and draft posts, media files and total views. Below that are recent posts, quick actions (new post, upload media, manage categories) and recent activity.

Shop

This group is hidden when commerce is switched off. See Commerce for how the shop works.

• Products (/admin/products): the catalogue, with variants, stock, prices, brands and product categories.
• Orders (/admin/orders): order list and detail, status changes, refunds (admin only). Read-only for managers.
• Customers (/admin/customers): customer records. Read-only for managers.

Content

• Posts (/admin/posts): articles and pages together, filterable by status, with bulk publish, draft, trash and delete. See Content and media.
• Categories (/admin/categories): name, slug and description for post categories.
• Media (/admin/media): the media library. Upload, search, add alt text, replace, delete.
• Messages (/admin/messages, admin only): contact-form messages (mark read or unread, delete), the newsletter subscriber list, and a "Send a newsletter" panel.
• Translations (/admin/translations): what is still untranslated, per language, for articles and products. See Internationalisation.
• Import a site (/admin/import, admin only): the WordPress importer, plus CSV/JSON export and import of your own collections. See Importing.
• Content types (/admin/content-types, admin only): define your own collections and taxonomies. See Custom content types.

Collections

Below the fixed groups there is a Collections heading with one link for each registered content type. That includes the ones you built, the ones plugins declare, and comments and reviews when those are switched on. Each link opens the entries screen at /admin/content/<type>. Admins and editors see this group.

Site

• Themes (/admin/themes, admin only): install and activate themes, then customise site identity, colours, typography and custom CSS, with a live preview. See Themes.
• Insights (/admin/insights): reading totals (most read, views by category and by language) and broken links in your content. It also shows missing images, dead URLs that paid traffic is landing on, and 30-day series for orders, messages and subscribers. View counts are running totals with no time axis, and the screen says so.
• Redirects (/admin/redirects): redirect rules (301, 302 or 410 Gone, with an optional note) next to a report of addresses that led nowhere. You can sort that report by paid clicks lost, times requested or most recent.
• Legal pages (/admin/legal, admin only): ready-made templates to activate. See Content and media.

System

All admin only.

• Users (/admin/users): create, edit, deactivate and delete accounts, reset passwords, and filter by role or status. What each role may do is a matrix of the capabilities above for editor, author, manager and viewer. Only the changes you make are stored, so capabilities added in later releases keep their built-in defaults. Act as lets an admin sign in as a non-admin user to see what they see. Every action is recorded as that user until you switch back. You cannot switch onto another admin.
• Plugins (/admin/plugins): installed plugins from the registry and from manifests, with activation. See Plugins.
• API keys (/admin/api-keys): see API keys below.
• Webhooks (/admin/webhooks): register an endpoint URL and a comma-separated event list (* for everything, or a post.* style wildcard), then inspect deliveries. The signing secret is shown once. See Webhooks.
• Background jobs (/admin/operations): the scheduler, including scheduled posts that are past their time and still waiting. Also shows off-site backup status, request timings (busiest paths, slowest requests) and the outbound email log.
• Email wording (/admin/email-templates): reword the subject and body of each email the site sends, with a server-rendered preview. See Email.
• Data requests (/admin/privacy): answer a GDPR access or erasure request from an email address. Look first ("What we hold"), export in one click, and erase only after the record is on screen and you type a confirmation. The screen also shows the cookie declaration and consent receipts.
• Audit log (/admin/audit): logins, security events, and content and commerce edits. Filter by action prefix, actor and date range. Price, stock and status changes record before and after values. Other fields are recorded by name only.
• Tools (/admin/tools): download a JSON backup (files over 10 MB are skipped) and restore one. It also reports section health (section classes in your content that this build can no longer style) and which editor patterns are offered and which were rejected. See Backups and storage.
• Settings (/admin/settings): grouped as Site (General, Reading), Shop (selling, currency, product fields, unpaid orders, order limits, payment providers, new-sale notifications, EU right of withdrawal), Marketing (analytics tags) and Advanced (AI assistant, anti-spam check, maintenance mode). Your own settings lets you declare extra typed setting groups. A group marked public can be read by a decoupled front end through /api/settings/get. See Configuration.

Plugin screens

Plugins can add admin pages under /admin/plugin/<id>/<page>. They appear under a Plugins heading in the sidebar and in the command palette, labelled by the plugin itself.

Profile and two-factor sign-in

Every staff member has /admin/profile, whatever their role. There you can:

• change your name and email (your role is shown but cannot be changed here);
• change your password (at least 8 characters);
• opt in to a public author archive at /blog/author/<name>, but only if an admin has enabled author archives in Settings → Reading;
• set up two-factor authentication.

Two-factor uses a time-based one-time code (TOTP) from any authenticator app. Setup shows a secret and an otpauth:// URI. You confirm with a 6-digit code, and are then shown backup codes once. Each backup code works once. To turn two-factor off you need a current code or a backup code.

Two-factor can only be enabled when an email channel is configured, because email is the recovery path. Until then the profile screen says so. See Email and Security.

On the login page, a user with two-factor on is asked for the code after their password, and a backup code is accepted there too. When email is configured, the login page also offers an emailed sign-in link.

API keys

/admin/api-keys (admin only) mints bearer keys for headless front ends, cross-origin clients and agents.

Field	Meaning
Name	A label for you, such as my-frontend
Role	The role the key acts as: admin, editor, author, manager or viewer
Scopes	Optional. Comma-separated resource:action pairs. Leave empty for the role's full access
Expires in days	Optional expiry

The secret (prefixed abk_) is shown once, when you create the key. The list shows each key's prefix, role, scopes, expiry and when it was last used. Rotate replaces the secret immediately. Revoke cannot be undone.

Scopes narrow a key further than its role allows. The scope-gated resources are posts, content, media, products, orders, customers and messages. The actions are read, write and *, and * on its own grants everything:

posts:read
content:*
posts:write,media:write
*

GET, HEAD and OPTIONS requests need :read, and everything else needs :write. A few more endpoints are covered by these scopes. /api/commerce/*, /api/shipping-methods and /api/coupons fall under products, and /api/contact falls under messages. Endpoints outside these resources are governed by the key's role only. Source: src/lib/api-key-scopes.ts.

For how to use a key, see Headless and REST API.

Admin language

The admin interface ships in English, Greek and German. The language is chosen from your browser's Accept-Language, limited to locales the site serves (SITE_LOCALES) that also have a bundled catalogue. If none match, the site's default locale is used, then English. See Internationalisation.

See also

• Content and media
• Custom content types
• Configuration
• Security
• Headless and REST API
• Webhooks
• Commerce