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

# Authentication

> Authenticate with the QWED API using API keys. Learn header and SDK authentication methods, key formats, environment variables, and security best practices.

How to authenticate with the QWED API.

## API keys

All requests require an API key.

### Header authentication

```bash theme={null}
curl -H "X-API-Key: qwed_your_key" https://api.qwedai.com/v1/health
```

### SDK authentication

```python theme={null}
from qwed_sdk import QWEDClient

client = QWEDClient(api_key="qwed_your_key")
```

## Environment variables

Set your API key as an environment variable:

```bash theme={null}
export QWED_API_KEY=qwed_your_key
```

Then the SDK will auto-detect it:

```python theme={null}
client = QWEDClient()  # Uses QWED_API_KEY env var
```

## API key format

| Prefix        | Type             |
| ------------- | ---------------- |
| `qwed_`       | Standard API key |
| `qwed_test_`  | Test/sandbox key |
| `qwed_agent_` | Agent token      |

## Security best practices

1. **Never commit API keys** to version control
2. **Use environment variables** in production
3. **Rotate keys regularly** using the dashboard
4. **Set IP allowlists** for production keys
5. **Use test keys** for development

## Agent authentication

Agent tokens are separate from API keys and are used for agent-specific endpoints.

```python theme={null}
# Register agent (requires API key auth)
response = client.register_agent(name="MyBot", ...)
agent_token = response["agent_token"]  # qwed_agent_...

# Use agent token via X-Agent-Token header
client.verify_action(
    agent_id=response["agent_id"],
    action={...}
)
```

Agent tokens are passed via the `X-Agent-Token` header:

```bash theme={null}
curl -X POST https://api.qwedai.com/v1/agents/42/verify \
  -H "X-Agent-Token: qwed_agent_..." \
  -H "Content-Type: application/json" \
  -d '{"query": "What is 2+2?"}'
```

## Scopes

API keys can have restricted scopes:

| Scope              | Access                 |
| ------------------ | ---------------------- |
| `verify:read`      | Verification endpoints |
| `agent:write`      | Agent management       |
| `attestation:read` | Attestation queries    |
| `admin:all`        | Full access            |

## Auth endpoints

The following endpoints manage user accounts and API keys via JWT-based authentication.

### POST /auth/signup

Create a new user and organization. Returns a JWT token for immediate use.

**Request:**

```json theme={null}
{
  "email": "user@example.com",
  "password": "securepassword",
  "organization_name": "Acme Corp"
}
```

**Response:**

```json theme={null}
{
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "token_type": "bearer",
  "user": {
    "id": "1",
    "email": "user@example.com",
    "org_id": "1",
    "role": "owner"
  }
}
```

### POST /auth/signin

Sign in an existing user.

**Request:**

```json theme={null}
{
  "email": "user@example.com",
  "password": "securepassword"
}
```

**Response:** Same format as `/auth/signup`.

### GET /auth/me

Get the current authenticated user's information. Requires a `Bearer` token in the `Authorization` header.

```bash theme={null}
curl -H "Authorization: Bearer eyJhbG..." https://api.qwedai.com/v1/auth/me
```

### POST /auth/api-keys

Generate a new API key for the current user's organization. Requires JWT authentication.

**Request:**

```json theme={null}
{
  "name": "Production Key"
}
```

**Response:**

```json theme={null}
{
  "id": "1",
  "name": "Production Key",
  "key": "qwed_live_abc123...",
  "created_at": "2026-03-20T12:00:00Z"
}
```

<Warning>The `key` field is only returned once at creation time. Store it securely.</Warning>

### GET /auth/api-keys

List all active API keys for the current user's organization.

### DELETE /auth/api-keys/{key_id}

Revoke an API key. Performs a soft delete.

## Audit endpoints

These endpoints require JWT authentication (Bearer token) and return data scoped to the authenticated user's organization.

### GET /audit/logs

Get audit logs for the current organization.

| Parameter | Type    | Default | Description                       |
| --------- | ------- | ------- | --------------------------------- |
| `limit`   | integer | `50`    | Maximum records (max 200)         |
| `status`  | string  | —       | Filter by `verified` or `blocked` |

### GET /audit/logs/{log_id}

Get detailed information for a single audit log entry.

### GET /audit/export

Export audit logs as a CSV file (up to 1,000 records).