> ## Documentation Index
> Fetch the complete documentation index at: https://atlas.rebuildingus.org/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> Choose the right Atlas authentication path for public data, API keys, OAuth, and MCP clients.

## Overview

Atlas has three access patterns:

| Pattern            | Best for                                                          | Credentials  |
| ------------------ | ----------------------------------------------------------------- | ------------ |
| Public read access | Searching public actors, places, sources, and taxonomy.           | None         |
| API keys           | Server-side scripts, imports, exports, and workspace automations. | `X-API-Key`  |
| OAuth              | MCP clients and advanced delegated access.                        | Bearer token |

Use the generated reference for endpoint-level auth requirements. Use this page
to choose the right model before you build.

## Public read access

Most public directory reads do not require credentials. This includes actor
search, place pages, entity sources, issue areas, and domains.

Public access is intentionally useful, but it has the lowest rate limit. If a
script becomes part of a regular workflow, authenticate it.

## API keys

Use API keys for server-to-server integrations:

* Scheduled exports into a CRM or data warehouse.
* Workspace reports, briefs, lists, watches, or usage proof.
* Discovery run automation.
* Higher-volume directory reads.

Create keys from Atlas account settings. Store them as secrets and send them in
the `X-API-Key` header:

```bash theme={null}
curl -H "X-API-Key: your-api-key" \
  "https://atlas.rebuildingus.org/api/discovery-runs"
```

Do not put API keys in browser code, mobile apps, public repositories, shared
notebooks, or copied examples.

## OAuth and MCP

Use OAuth when the user is granting access to a compliant client, especially an
MCP client such as Claude Desktop, Claude Code, Copilot, Gemini, or Codex.

Most users should not configure OAuth endpoints by hand. They give the client
the Atlas MCP server URL:

```text theme={null}
https://atlas.rebuildingus.org/mcp
```

The client follows Atlas metadata, opens a browser sign-in flow, receives
tokens, and refreshes them when needed.

<Card title="MCP for AI assistants" icon="robot" href="/docs/mcp/overview">
  Use Atlas from compliant AI assistants through the hosted MCP endpoint.
</Card>

## Workspace binding

Workspace APIs and assistant access use a workspace context. Single-workspace
users are selected automatically. Multi-workspace users pick the workspace
during consent.

If an integration writes or exports data, store the workspace id alongside the
artifact. Do not mix public directory records with private workspace notes
unless the API response explicitly says a record is public.

## When auth fails

Use the error response to choose the next action:

| Signal             | What to check                                                       |
| ------------------ | ------------------------------------------------------------------- |
| `401 Unauthorized` | Missing or invalid API key/token.                                   |
| `403 Forbidden`    | Valid identity, but plan, workspace, or permission is insufficient. |
| `429 Rate limited` | Use an authenticated request, reduce volume, or upgrade plan.       |

For exact OAuth metadata, scopes, and token behavior, use the generated
reference and the MCP docs.

## Next steps

<CardGroup cols={2}>
  <Card title="Rate limits" icon="gauge" href="/docs/api/rate-limits">
    Understand limits by access pattern.
  </Card>

  <Card title="Workspace visibility" icon="lock" href="/docs/api/guides/workspace">
    Keep private workspace context separate from public records.
  </Card>

  <Card title="Generated reference" icon="code" href="/docs/api/reference">
    Check exact endpoint auth and schemas.
  </Card>

  <Card title="Plans & pricing" icon="credit-card" href="/docs/account/pricing">
    See which plans include API keys and MCP access.
  </Card>
</CardGroup>