# Authentication: OAuth & Personal Access Tokens

How to authenticate to Briefs programmatically — through the MCP server
(https://sharebriefs.com/brief/mcp) or the REST API (https://sharebriefs.com/brief/api).
Reading a public Brief needs no authentication; every other action does.

## Two methods

1. **OAuth** — for MCP clients that support it (Claude Code, Claude Desktop, Claude web). The
   client takes the user through a browser sign-in and a consent screen; the approved
   permissions (scopes) are bound to that connection. Best for interactive use — no secret to
   copy or store.
2. **Personal Access Token (PAT)** — a long-lived bearer token the user generates once. Works
   for the REST API and for any MCP or HTTP client that accepts a token. Best for scripts,
   servers, and headless agents.

## Generating a Personal Access Token

PATs are created from the website, not via the API:

1. Sign in at https://sharebriefs.com.
2. Open Settings: https://sharebriefs.com/settings.
3. Create a new API key and give it a descriptive name (one per integration is good practice).
4. Copy the token immediately — it is shown only once and starts with `sb_`. Briefs stores
   only a hash and cannot display it again.
5. List or revoke tokens from the same page; revoking immediately cuts off anything using
   that key.

## Using a token

Send it as a bearer token:

```
Authorization: Bearer sb_...
```

- REST API base URL: `https://api.sharebriefs.com` — see https://sharebriefs.com/brief/api.
- MCP server URL: `https://mcp.sharebriefs.com` — see https://sharebriefs.com/brief/mcp.

## Scopes & access

- **Personal Access Tokens have full access** to everything the user can do: read and write
  Briefs, manage collaborators, and manage organizations.
- **OAuth connections carry only the scopes approved at consent.** Scopes cover reading and
  writing Briefs, reading the user's profile, and reading and writing organizations. If a
  connection lacks write access, content-changing tools fail — reconnect and approve the
  needed permissions.

## Security etiquette (for agents)

- Treat a PAT like a password. Never write it into a Brief, commit it to a repo, or paste it
  anywhere it will be shared.
- Prefer OAuth for interactive sessions; reach for a PAT only when a token is actually
  required.
- If a token may have leaked, revoke it at https://sharebriefs.com/settings and issue a new
  one.
- Use a separate, named token per tool or integration so one can be revoked without breaking
  the others.

## Related Briefs

- Using the MCP server: https://sharebriefs.com/brief/mcp
- REST API reference: https://sharebriefs.com/brief/api
- Concept overview: https://sharebriefs.com/brief/intro