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 answers 401 with a WWW-Authenticate challenge naming the protected-resource metadata — the signal your client uses to start sign-in. The public read tools are unaffected and stay anonymous.

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`

A client can only be granted scopes it registered for. A client that registers without naming a scope may request any of the three. A client that registers with a scope is limited to those scopes: other scopes it requests at authorization are dropped, and a request with none of its registered scopes returns invalid_scope.

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-resource

The 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.

Apps name themselves when they register, so the consent page also shows where you’ll be sent after approving. Apps from Claude, ChatGPT and VS Code are marked as verified, and an app running on your own computer (a CLI or a code editor) is labelled as one. Anything else is marked Unverified app along with the site it sends you to. Allow it only if you started the connection yourself. After that, write tools work without re-prompting until the token expires, at which point the refresh token renews it.

In Claude Code you can also start it yourself at any time — run /mcp, pick styleref, and authenticate. The server shows as needing authentication once an account-scoped tool has been tried.

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 — login and token storage.