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

# Authentication

> How to authenticate to the AutoSage API with API keys and sessions.

AutoSage supports two kinds of caller: **API keys** for your application, and **user sessions** for the dashboard. Most integrations use API keys.

## API keys

Create keys in the dashboard under your environment. A key is a bearer token you send on every request:

```bash theme={null}
curl https://api.autosage.ai/api/v1/tenants \
  -H "Authorization: Bearer sk_live_your_key_here"
```

<Note>
  The API selects API-key authentication when the token starts with `sk_`. Always send the full token including the `sk_` prefix, and keep the `Bearer ` scheme.
</Note>

### Key prefixes

The prefix tells you which environment type a key belongs to:

| Prefix     | Environment types          |
| ---------- | -------------------------- |
| `sk_live_` | `production`, `personal`   |
| `sk_test_` | `dev`, `staging`, `custom` |

### What a key carries

Every key is bound to configuration that determines what it can reach:

<ParamField path="environment" type="string">
  The single environment the key belongs to. A key can never access another environment.
</ParamField>

<ParamField path="tenant access" type="string[]">
  An optional list of tenant IDs the key may use. **Leave it empty to grant access to every tenant in the environment**, or list specific tenant IDs to scope the key down.
</ParamField>

<ParamField path="knowledge base access" type="string[]">
  An optional list of knowledge base IDs, narrowing access further within the allowed tenants.
</ParamField>

<ParamField path="scopes" type="string[]">
  The permissions the key holds, such as `tenants:read`, `knowledge_bases:write`, `query:rag`. See [Access & scopes](/developers/concepts/access-scopes).
</ParamField>

<Tip>
  For customer-facing products, create one key per environment and scope requests to individual customers with a **tenant per customer** plus the `external_subject_id` field on chats — rather than minting a key per customer. See [Tenancy](/developers/concepts/tenancy).
</Tip>

### Default scopes

If you don't specify scopes when creating a key, it receives a sensible default set for read/write on tenants, knowledge bases, and documents, plus `query:rag` for running chats.

## User sessions

Dashboard users authenticate with email/password or Google OAuth through the endpoints under `/api/auth`. Sessions are cookie-based; send the session cookie returned by sign-in. Session auth is required for organization-level administration — managing members, roles, environments, and invitations — which is intentionally not exposed to API keys.

## Choosing the right caller

<CardGroup cols={2}>
  <Card title="Use an API key" icon="robot">
    Provisioning tenants and knowledge bases, ingesting documents, running agents and chats, serving your end users.
  </Card>

  <Card title="Use a user session" icon="user">
    Creating organizations, managing team members and roles, creating environments, accepting invitations.
  </Card>
</CardGroup>

## Rotating and revoking keys

Keys can be revoked at any time from the dashboard, and revoked keys are disabled immediately. Keys do not expire by default, but you can configure an expiration when creating one. Rotate keys periodically and scope each key to only the tenants and permissions it needs.

<Warning>
  Treat `sk_...` keys like passwords. Never embed a key in client-side code or a public repository. For browser or mobile clients, call the AutoSage API from your own backend.
</Warning>