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

# Authentication Quick Reference

> Copy-paste curl commands for creating API keys, listing active keys, revoking credentials, and exchanging keys for access tokens in Sawmills.

## API Key Commands

### Create API Key

```bash theme={null}
curl -X POST "https://api.sawmills.ai/v1/user-api-keys" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"label": "My Key"}'
```

<Note>
  **JWT Token**: Get `YOUR_JWT_TOKEN` from Chrome DevTools → Network tab → Find API request → Copy Authorization header value (after "Bearer ").
</Note>

### List API Keys

```bash theme={null}
curl -X GET "https://api.sawmills.ai/v1/user-api-keys" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"
```

### Revoke API Key

```bash theme={null}
curl -X DELETE "https://api.sawmills.ai/v1/user-api-keys/{key_id}" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"
```

## Token Commands

### Exchange API Key for Token

```bash theme={null}
curl -X POST "https://api.sawmills.ai/v1/token" \
  -H "Authorization: ApiKey sk_test.abc123def4.xyz789uvw0123456789abcdef" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### Use Token for API Call

```bash theme={null}
curl -X GET "https://api.sawmills.ai/v1/user-api-keys" \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."
```

## Authentication Headers

| Purpose                | Header Format                   | Example                                                              |
| ---------------------- | ------------------------------- | -------------------------------------------------------------------- |
| Create/Manage API Keys | `Authorization: Bearer {jwt}`   | `Authorization: Bearer eyJhbGciOiJSUzI1NiIs...`                      |
| Exchange for Token     | `Authorization: ApiKey {key}`   | `Authorization: ApiKey sk_test.abc123def4.xyz789uvw0123456789abcdef` |
| Make API Calls         | `Authorization: Bearer {token}` | `Authorization: Bearer eyJhbGciOiJSUzI1NiIs...`                      |

## Common Error Codes

| Code                | Meaning                  | Solution                     |
| ------------------- | ------------------------ | ---------------------------- |
| `UNAUTHENTICATED`   | Invalid credentials      | Check API key/token validity |
| `PERMISSION_DENIED` | Insufficient permissions | Verify scopes                |
| `NOT_FOUND`         | Resource not found       | Check if key exists          |
| `INVALID_ARGUMENT`  | Bad request              | Validate parameters          |

## Environment Variables

```bash theme={null}
## Required
export SAWMILLS_API_KEY="sk_test.abc123def4.xyz789uvw0123456789abcdef"
export SAWMILLS_BASE_URL="https://api.sawmills.ai"

# Optional
export SAWMILLS_TIMEOUT="30"
export SAWMILLS_RETRY_ATTEMPTS="3"
```

## Testing Authentication

### Test API Key

```bash theme={null}
# Test with your API key
curl -X POST "https://api.sawmills.ai/v1/token" \
  -H "Authorization: ApiKey YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}' \
  -w "HTTP Status: %{http_code}\n"

# Expected: HTTP Status: 200
```

### Test Token Exchange

```bash theme={null}
# Test with valid API key
curl -X POST "https://api.sawmills.ai/v1/token" \
  -H "Authorization: ApiKey $SAWMILLS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}' \
  -w "HTTP Status: %{http_code}\n"

# Expected: HTTP Status: 200
```

### Test API Call

```bash theme={null}
# Test with access token
curl -X GET "https://api.sawmills.ai/v1/user-api-keys" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -w "HTTP Status: %{http_code}\n"

# Expected: HTTP Status: 200
```

## Troubleshooting Checklist

* [ ] API key is correctly formatted
* [ ] API key is active and not revoked
* [ ] Authorization header uses correct scheme (`ApiKey` vs `Bearer`)
* [ ] Token hasn't expired (30 minutes default)
* [ ] HTTPS is being used
* [ ] No extra whitespace in credentials
* [ ] Correct environment (test vs live)