Authentication & scopes
Anonymous callers can search, fetch, and apply public styles. Account-scoped tools require an OAuth 2.1 connection to a StyleRef account. This page covers the scopes and the flow.
An anonymous call to an account-scoped tool doesn’t fail with a 401 — it returns a message telling the user to connect, often with a deep link to complete the action on the web.
Scopes
| Scope | Grants | Tools |
|---|---|---|
styles:read | Read your library | list_my_styles |
styles:write | Create and modify styles | save_style, fork_style, create_style, update_style, publish_style, set_style_visibility |
extract | Run AI extractions | extract_style, check_extraction_status |
The authorization flow
StyleRef is an OAuth 2.1 authorization server. Clients use:
- Authorization code with PKCE (
S256) — no client secret needed for public clients. - Dynamic client registration — clients register themselves at the registration endpoint.
- Refresh tokens — long-lived access without re-consenting.
Discovery follows the standard metadata endpoints, so a compliant MCP client configures itself from the endpoint alone:
https://styleref.io/.well-known/oauth-authorization-server
https://styleref.io/.well-known/oauth-protected-resourceThe authorization server advertises:
| Field | Value |
|---|---|
| Issuer | https://styleref.io |
| Authorization endpoint | https://styleref.io/oauth/authorize |
| Token endpoint | https://styleref.io/api/oauth/token |
| Registration endpoint | https://styleref.io/api/oauth/register |
| Grant types | authorization_code, refresh_token |
| PKCE methods | S256 |
| Scopes | styles:read, styles:write, extract |
How connecting looks per client
Most MCP clients handle the flow for you: the first time an agent calls an account-scoped tool, the client opens StyleRef’s consent page in a browser, you approve the requested scopes, and the client stores the token. After that, write tools work without re-prompting until the token expires, at which point the refresh token renews it.
For the terminal, npx styleref login runs the same flow with a loopback redirect and stores the token locally. See the CLI reference.
Next steps
- Tools reference — which tools need which scope.
- Connect your client — set up the server first.
- CLI reference —
loginand token storage.