# Blitera API Agent Guide

This guide is for automation agents and trusted backend integrations that call the Blitera API.

## Read This First

- Use API keys only for server-to-server automation.
- Never expose an API key in browser code, mobile clients, public repositories, logs, screenshots, or prompts sent to third-party tools.
- Never send `account_id` in request bodies or query strings. Blitera derives tenant identity from the authenticated principal.
- Treat `403` responses as security boundaries. Do not bypass, retry with guessed workspace IDs, or downgrade protections.
- Confirm with the operator before running destructive requests such as `DELETE` or broad write operations.

## Authentication Modes

### API key

Use the `X-API-Key` header:

```http
X-API-Key: $BLITERA_API_KEY
```

API keys support scoped access to personal assets by default. Workspace access requires an explicit workspace allowlist on the key.

### Session only

Owner governance endpoints require the authenticated Blitera browser session. Do not call these endpoints with `X-API-Key`.

Session-only examples include:

- API key creation, update, listing, and revocation.
- Dedicated API key activity log and export.

## Scopes

| Scope | Purpose |
| --- | --- |
| `links:read` | Read links and link details. |
| `links:write` | Create or update links. |
| `links:delete` | Delete links. |
| `files:read` | Read file metadata and file lists. |
| `files:write` | Upload or reuse files. |
| `files:delete` | Delete files. |
| `collections:read` | Read collections and collection details. |
| `collections:write` | Create or update collections and collection items. |
| `collections:delete` | Delete collections and collection items. |
| `audit:read` | Read and export public access audit logs. |

## Workspace Allowlist

Personal scope is available to a valid key when the matching business scope is present.

Workspace scope requires both:

- The business scope required by the endpoint.
- The requested `workspace_id` in the key allowlist.

If the workspace is not allowlisted, stop and report the `403 workspace_forbidden` response. Do not enumerate workspace IDs.

## Public API Workflows

### Export public access audit

Use this when the operator asks for access history, public link audit evidence, SIEM ingestion, or CSV access reports.

PowerShell:

```powershell
$env:BLITERA_BASE_URL = "https://example.blitera.com"
$env:BLITERA_API_KEY = "<set from your secret manager>"
.\scripts\api\export-audit-logs.ps1 -OutputPath ".\access_audit.csv"
```

Bash:

```bash
export BLITERA_BASE_URL="https://example.blitera.com"
export BLITERA_API_KEY="<set from your secret manager>"
./scripts/api/export-audit-logs.sh ./access_audit.csv
```

Required scope: `audit:read`.

### List public access audit rows

Use this for paginated monitoring or diagnostics.

PowerShell:

```powershell
$env:BLITERA_BASE_URL = "https://example.blitera.com"
$env:BLITERA_API_KEY = "<set from your secret manager>"
.\scripts\api\list-audit-logs.ps1 -Limit 25
```

Bash:

```bash
export BLITERA_BASE_URL="https://example.blitera.com"
export BLITERA_API_KEY="<set from your secret manager>"
BLITERA_LIMIT=25 ./scripts/api/list-audit-logs.sh
```

Required scope: `audit:read`.

### List links

Use this when the operator asks for link inventory.

PowerShell:

```powershell
$env:BLITERA_BASE_URL = "https://example.blitera.com"
$env:BLITERA_API_KEY = "<set from your secret manager>"
$env:BLITERA_WORKSPACE_ID = "ws_333c92d68a7545aa9060"
.\scripts\api\list-links.ps1 -Limit 25
```

Bash:

```bash
export BLITERA_BASE_URL="https://example.blitera.com"
export BLITERA_API_KEY="<set from your secret manager>"
export BLITERA_WORKSPACE_ID="ws_333c92d68a7545aa9060"
BLITERA_LIMIT=25 ./scripts/api/list-links.sh
```

Required scope: `links:read`.

## Dedicated API Key Activity

API key activity is not the same as public access audit.

- Public access audit tracks external link visits, downloads, and redemption events.
- API key activity tracks machine calls made with API keys.

Dedicated API key activity endpoints are owner governance endpoints and are session-only:

- `GET /api/keys/audit/log`
- `GET /api/keys/audit/export`

An API key must not be used to read its own activity.

## Machine-Readable Manifest

Read `/api-agent/blitera-api-manifest.json` before selecting endpoints. The manifest describes auth mode, required scopes, workspace behavior, and destructive operations.

## Error Handling

- `401 Unauthorized`: credentials are missing, invalid, or expired.
- `403 api_scope_required`: the key is valid but lacks the required scope.
- `403 workspace_forbidden`: the workspace is not allowlisted or the session principal is not an active member.
- `403 feature_locked`: the account plan does not include the requested capability.
- `404 Not Found`: the resource does not exist in the authenticated scope.
- `429 Too Many Requests`: back off and retry later.

## Operator Confirmation Rules

Ask for explicit confirmation before:

- Creating, updating, or deleting links, files, or collections.
- Exporting broad audit datasets outside the current date range requested by the operator.
- Using a workspace ID not provided by the operator or a trusted configuration source.
- Persisting API output to shared folders or external systems.