# Authentication

All API requests require authentication via a Bearer token in the Authorization header.

## Bearer Token

Include your API key in the Authorization header of every request.

```bash
curl https://api.samreshuuu.com/api/v1/sessions \
  -H "Authorization: Bearer sk-org-your_api_key"
```

## Language Examples

**Python**

```python
import requests

API_KEY = "sk-org-your_api_key"
BASE_URL = "https://api.samreshuuu.com/api/v1"

headers = {"Authorization": f"Bearer {API_KEY}"}
response = requests.get(f"{BASE_URL}/sessions", headers=headers)
```

**Node.js**

```typescript
const API_KEY = "sk-org-your_api_key";
const BASE_URL = "https://api.samreshuuu.com/api/v1";

const response = await fetch(`${BASE_URL}/sessions`, {
  headers: { Authorization: `Bearer ${API_KEY}` },
});
const data = await response.json();
```

**cURL**

```bash
curl https://api.samreshuuu.com/api/v1/sessions \
  -H "Authorization: Bearer sk-org-your_api_key"
```

## Organization Context

If you belong to multiple organizations, pass the X-Org-Id header to select the context.

```bash
curl https://api.samreshuuu.com/api/v1/sessions \
  -H "Authorization: Bearer sk-org-your_api_key" \
  -H "X-Org-Id: org_abc123"
```

## Token Format

API keys are prefixed with `sk-org-`. The full secret is shown only once, at creation — store it securely. List and revoke endpoints only ever return the key prefix, never the secret.

## Scopes

Every key carries a list of scopes, enforced per endpoint. If a key is missing the scope an endpoint requires, the request fails with `403 AUTH_PERMISSION_DENIED`. A key with the `admin` scope bypasses every per-scope check. New keys default to `write:tools` when no scopes are specified.

| Scope | Grants |
| --- | --- |
| `read:tools` | Read tool and connector metadata |
| `write:tools` | Execute tools and connectors |
| `read:data` | Read your organization's data |
| `chat` | Call the OpenAI-compatible `/v1/chat/completions` endpoint |
| `connector:gateway` | Direct connector gateway access |
| `admin` | Full access — bypasses per-scope checks |

## Managing API Keys

Keys are issued, listed, and revoked per organization. Each key expires after `expires_in_days` (default 90, range 1–365).

```bash
# Create a key — the full secret is returned once
curl -X POST https://api.samreshuuu.com/api/v1/organizations/$ORG_ID/api-keys \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "production", "scopes": ["chat", "write:tools"], "expires_in_days": 90}'

# List keys — prefix, scopes, and last_used_at only
curl https://api.samreshuuu.com/api/v1/organizations/$ORG_ID/api-keys \
  -H "Authorization: Bearer $ADMIN_TOKEN"

# Revoke a key
curl -X DELETE https://api.samreshuuu.com/api/v1/organizations/$ORG_ID/api-keys/$KEY_ID \
  -H "Authorization: Bearer $ADMIN_TOKEN"
```

## Authentication Errors

An invalid or expired token results in a 401 response.

```json
{
  "detail": {
    "code": "AUTH_TOKEN_EXPIRED",
    "message": "The provided authentication token has expired.",
    "hint": "Generate a new API token in your dashboard."
  }
}
```