Authentication & access
Use a personal access token for scripts, or authorize an assistant through the StuffOwl sign-in and consent flow.
Create a personal access token
- Open Settings → Access tokens while signed in.
- Give the token a recognizable name and choose 7, 30, 90, or 365 days.
- Select only the permissions the integration needs.
- Create the token and save it. The full value is shown only once.
For photo naming, select inventory:read, inventory:write, and photos:read. Deleting inventory and printing labels are separate opt-ins.
Tokens begin with so_pat_. StuffOwl stores a hash, not the token secret. Keep the value in a secret store or environment variable; never put it in a URL, shared prompt, repository, or public screenshot.
Permission reference
| Scope | Allows |
|---|---|
| inventory:read | Read items, places, boxes, tags, search results, and history |
| inventory:write | Create, rename, classify, and move inventory; update checks |
| inventory:delete | Delete inventory records |
| photos:read | View and download private photos and attachments |
| photos:write | Upload photos and receipts |
| photos:delete | Delete photos and attachments |
| labels:read | Read label images and printer payloads |
| labels:print | Queue labels and record completed prints |
Limits and ownership
- Each token belongs to one account and one inventory. Removing that membership invalidates access.
- Limited members can use only read permissions.
- Up to 25 active personal tokens per account per inventory.
- Each PAT allows 120 authenticated requests per minute. An MCP tool call can also make an internal API request, so plan for fewer than 120 tool calls per minute.
- Tokens do not grant account, admin, or token-creation access.
Assistant sign-in with OAuth
An OAuth-capable assistant opens StuffOwl’s sign-in page and then a permission screen. Check the application name and requested access, then allow or cancel the connection. Photo access lets the assistant receive images you ask it to inspect.
The server supports authorization code flow with S256 PKCE, exact registered callback URLs, resource-bound access tokens, and rotating refresh tokens. Access tokens last 15 minutes; offline connections can refresh access for up to 30 days under the provider’s session rules.
The protected resource is https://stuffowl.com/mcp. Discovery is available at protected-resource metadata and authorization-server metadata. OAuth clients should discover registration and token URLs instead of hard-coding them.
Revoke or rotate access
In Access tokens, revoke a PAT or disconnect an assistant. A PAT cannot be recovered; create a replacement and update the integration. To rotate without interruption, configure and verify the new token before revoking the old one.
Revoking access prevents subsequent authenticated reads and writes. It does not remove data that an assistant already received or reverse changes already applied. Use an enrichment batch’s undo operation when appropriate.