Lune Research permissions

Every OAuth access token and personal access token has an explicit set of scopes. Lune checks the required scope on every protected request. A credential cannot inherit additional authority from the person or team that created it.

Scope reference

Scope	OAuth	PAT	What it grants
`papers:read`	Yes	Yes	Search papers, read available full text, follow citations, and compare papers.
`guidance:read`	Yes	Yes	Search and read curated scientific workflow guidance.
`subs:rw`	Yes	Yes	Choose which conferences appear in results. The name is kept for compatibility.
`account:read`	Yes	Yes	Read account identity, plan, daily allowance, and credit balance.
`keys:rw`	Yes	No	Create a PAT during an approved OAuth flow. OAuth cannot list or revoke PATs.
`workspace:read`	No	Yes	Search and read documents in the active Lune Workspace.

The OAuth authorization server publishes its supported set in scopes_supported. The PAT creation endpoint validates its own supported set and rejects an unknown scope instead of silently granting or dropping it.

Least-privilege examples

A literature search integration normally requests only papers:read. Add guidance:read if it also answers questions about experiment design, ablations, evaluation, peer review, or research writing. Add subs:rw only when the agent must change the team's conference selection. Add account:read only when it must report plan or usage state.

The first-party CLI requests keys:rw because lune install creates a separate PAT for a local MCP process after the user approves it. That OAuth scope is create-only. An OAuth connector cannot enumerate or revoke the team's existing keys, and the PAT it creates cannot carry keys:rw.

workspace:read is reserved for PATs. Lune's Workspace agent uses a managed, workspace-bound PAT so the model never receives a workspace ID and cannot switch to another workspace by changing a tool argument.

Defaults and reauthorization

A new user-created PAT defaults to papers:read, guidance:read, subs:rw, and account:read. Remove anything the integration does not need when creating the key. PAT scopes are immutable after creation. To change them, create a new key with the intended set, replace the old credential, and revoke the old key.

OAuth clients send a space-separated scope value during authorization. Lune clamps the request to the published OAuth set, shows every granted scope on the consent screen, and returns the granted set in the token response. If the client later needs another scope, it must run authorization again so the user can approve the new authority.

Insufficient scope response

An authenticated request without the required scope returns 403 Forbidden. The body names both sets so software can explain the exact fix:

{
  "detail": {
    "error": "insufficient_scope",
    "required": ["guidance:read"],
    "granted": ["papers:read"]
  }
}

Do not respond by asking for every scope. Request the missing scope only, then retry after the user approves or supplies a replacement credential.