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

# Authentication

> How to authenticate with the Bedrock API

# Authentication

Bedrock supports two authentication schemes. Most programmatic callers use an **API key**; the Bedrock portal and a handful of user-scoped endpoints use **token auth**.

## API Key (Bearer)

API keys are **scoped to your organization** and grant access to every resource your organization owns — templates, agents, adapters, tracing, and default adapter state.

### Getting an API Key

1. Sign in to the Bedrock portal
2. Navigate to **API Keys**
3. Click **Create API Key**, give it a name (e.g., "Production"), and copy the value immediately

<Warning>
  Save your API key immediately after creation. The full value is only displayed once and cannot be retrieved later.
</Warning>

### Using Your API Key

Include your API key in the `Authorization` header with the `Bearer` prefix:

```
Authorization: Bearer YOUR_API_KEY
```

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET https://api.bedrock.orinlabs.org/api/cloud/agents/ \
    -H "Authorization: Bearer bk_abc123..."
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      "https://api.bedrock.orinlabs.org/api/cloud/agents/",
      headers={"Authorization": "Bearer bk_abc123..."},
  )
  agents = response.json()
  ```

  ```typescript TypeScript theme={null}
  const response = await fetch("https://api.bedrock.orinlabs.org/api/cloud/agents/", {
    headers: {
      "Authorization": "Bearer bk_abc123..."
    }
  });
  const agents = await response.json();
  ```
</CodeGroup>

### API Key Scope

An API key's access follows the organization it belongs to:

| Resource                  | Access                                                   |
| ------------------------- | -------------------------------------------------------- |
| **Templates**             | Full CRUD on templates in your org                       |
| **Agents**                | Full CRUD — create, read, update, delete, run, tag, stop |
| **Traces**                | Read / write for traces on agents in your org            |
| **Adapters**              | Read org adapters; create / delete your own custom ones  |
| **Adapter Configs**       | Full CRUD on configs for templates in your org           |
| **Default Adapter State** | Contacts, messages, documents, projects, notifications   |

### Creating API Keys via API

You can also create API keys programmatically against `/api/organizations/api-keys/`:

```bash theme={null}
curl -X POST https://api.bedrock.orinlabs.org/api/organizations/api-keys/ \
  -H "Authorization: Bearer EXISTING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Production Key"}'
```

Response:

```json theme={null}
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Production Key",
  "key": "bk_live_xyz789...",
  "is_active": true,
  "created_at": "2026-01-15T10:30:00Z"
}
```

### Managing API Keys

List keys:

```bash theme={null}
curl -X GET https://api.bedrock.orinlabs.org/api/organizations/api-keys/ \
  -H "Authorization: Bearer YOUR_API_KEY"
```

Delete a key:

```bash theme={null}
curl -X DELETE https://api.bedrock.orinlabs.org/api/organizations/api-keys/KEY_ID/ \
  -H "Authorization: Bearer YOUR_API_KEY"
```

## Token Auth (portal / user-scoped)

The portal and the `/api/organizations/auth/*` endpoints use DRF's `TokenAuthentication`:

```
Authorization: Token YOUR_USER_TOKEN
```

Tokens are returned by:

* `POST /api/organizations/auth/signup/` — creates org + user + membership + token
* `POST /api/organizations/auth/login/` — returns a token for an existing user
* `POST /api/organizations/invites/{id}/accept/` — returns a token for the invitee

Tokens are **user-scoped**. They're most useful for the portal itself; prefer an org API key for backend-to-backend traffic.

Endpoints that commonly accept both (both `TokenAuthentication` and `APIKeyAuthentication` are installed): `/api/organizations/organizations/`, `/api/organizations/api-keys/`, `/api/templates/`.

## Security Best Practices

<CardGroup cols={2}>
  <Card title="Environment Variables" icon="leaf">
    Store API keys in environment variables, never hardcode in source.
  </Card>

  <Card title="Server-Side Only" icon="server">
    Never expose API keys in client-side code or public repositories.
  </Card>

  <Card title="Rotate Regularly" icon="rotate">
    Create new keys and delete old ones periodically.
  </Card>

  <Card title="Descriptive Names" icon="tag">
    Name keys by environment/purpose for easy auditing.
  </Card>
</CardGroup>

## Error Responses

| Status             | Meaning                                           |
| ------------------ | ------------------------------------------------- |
| `401 Unauthorized` | Missing or invalid API key / token                |
| `403 Forbidden`    | Valid key but the resource belongs to another org |

```json theme={null}
{
  "detail": "Authentication credentials were not provided."
}
```