Staff, scopes and keys
Every request to the admin API acts as someone: a staff member, an API key, an installed app or an AI agent. What it may do is a set of scopes, and every command checks the scopes it needs before it does anything.
Scopes
Section titled “Scopes”Scopes are named after an area and an access: products:read, orders:write,
customers:erase. A write scope includes its read scope. Personal data about customers
(names, emails, phones, addresses) needs customer_data:* scopes on top: a caller without
them gets those fields left out, and the response lists what was left out in redacted.
Staff members sign in with a password and, optionally, a second factor (an authenticator app, with recovery codes). Each has a role, a named set of scopes; the owner’s role has every scope. Staff invite others by email, and nobody can grant a scope they don’t hold themselves.
API keys
Section titled “API keys”- Secret keys (
hypha_sk_…) are for servers: scripts, integrations, a backend. They carry the scopes they were created with. - Publishable keys (
hypha_pk_…) are for storefronts. They reach only the storefront API, for one sales channel.
Keys are stored only as hashes, and shown once when created.
Apps and agents
Section titled “Apps and agents”Installed apps act with the scopes staff approved when installing them. AI agents act with their own grant, and a connected agent never exceeds the role of the person it acts for. See Build an app and Connect an AI agent.
Shoppers
Section titled “Shoppers”Shoppers sign in to the storefront with a six-digit code sent to their email; there are no passwords to leak. A signed-in shopper reaches their own orders, addresses, marketing choices and data, and nothing else.