# API Keys Documentation

## Overview

API keys provide programmatic access to your SaaS platform resources. Each API key can be configured with granular scope-based permissions to control exactly which resources and actions are allowed.

## Creating an API Key

1. Navigate to the **API Keys** page in the dashboard
2. Click **Create API Key**
3. Enter a descriptive name
4. Select an expiration period (optional)
5. Configure resource scopes and permissions
6. Click **Create API Key**
7. **Important**: Copy and save the API key immediately - it will not be shown again

## API Key Format

All API keys follow the format: `sk_<64-character-hex-string>`

Example: `sk_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6a7b8c9d0e1f2`

## Scope-Based Permissions

API keys use a scope-based permission model with the following structure:

### Available Resources

- **users** - User accounts and profiles
- **applications** - Application configurations
- **deployments** - Application deployments
- **database** - Database tables and queries
- **api_keys** - API key management (read-only)

### Available Actions per Resource

- **create** - Create new resources
- **read** - View and list resources
- **update** - Modify existing resources
- **delete** - Remove resources

### Permission Structure

```json
{
  "users": {
    "create": true,
    "read": true,
    "update": false,
    "delete": false
  },
  "applications": {
    "create": false,
    "read": true,
    "update": false,
    "delete": false
  },
  "database": {
    "create": false,
    "read": true,
    "update": false,
    "delete": false
  }
}
```

## Using API Keys

### Authentication

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

```bash
Authorization: Bearer sk_your_api_key_here
```

### Base URL

All API key endpoints are available under the `/v1` prefix:

```
https://your-domain.com/api/v1/
```

### Example Requests

#### List Users (requires `users:read` scope)

```bash
curl -X GET https://your-domain.com/api/v1/users \
  -H "Authorization: Bearer sk_your_api_key_here"
```

Response:
```json
{
  "data": [
    {
      "id": "uuid",
      "email": "user@example.com",
      "first_name": "John",
      "last_name": "Doe",
      "created_at": "2024-01-01T00:00:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 50,
    "totalPages": 3
  }
}
```

#### Get Application (requires `applications:read` scope)

```bash
curl -X GET https://your-domain.com/api/v1/applications/app-uuid \
  -H "Authorization: Bearer sk_your_api_key_here"
```

#### List Database Tables (requires `database:read` scope)

```bash
curl -X GET https://your-domain.com/api/v1/database/tables \
  -H "Authorization: Bearer sk_your_api_key_here"
```

#### Execute Database Query (requires `database:read` scope)

```bash
curl -X POST https://your-domain.com/api/v1/database/query \
  -H "Authorization: Bearer sk_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "SELECT * FROM my_table LIMIT 10"
  }'
```

**Note**: Only `SELECT` queries are allowed via API keys. System tables (`__sys_*`) cannot be queried.

## Available Endpoints

### Users API

| Method | Endpoint | Required Scope | Description |
|--------|----------|----------------|-------------|
| GET | `/v1/users` | `users:read` | List all users |
| GET | `/v1/users/:id` | `users:read` | Get user by ID |

### Applications API

| Method | Endpoint | Required Scope | Description |
|--------|----------|----------------|-------------|
| GET | `/v1/applications` | `applications:read` | List all applications |
| GET | `/v1/applications/:id` | `applications:read` | Get application by ID |

### Deployments API

| Method | Endpoint | Required Scope | Description |
|--------|----------|----------------|-------------|
| GET | `/v1/deployments` | `deployments:read` | List all deployments |
| GET | `/v1/deployments?applicationId=:id` | `deployments:read` | List deployments for an application |

### Database API

| Method | Endpoint | Required Scope | Description |
|--------|----------|----------------|-------------|
| GET | `/v1/database/tables` | `database:read` | List all database tables |
| POST | `/v1/database/query` | `database:read` | Execute SELECT query |

### API Keys API

| Method | Endpoint | Required Scope | Description |
|--------|----------|----------------|-------------|
| GET | `/v1/api-keys` | `api_keys:read` | List all API keys (metadata only) |

## Error Responses

### 401 Unauthorized

API key is missing, invalid, or expired.

```json
{
  "error": "Invalid or expired API key"
}
```

### 403 Forbidden

API key doesn't have required permissions.

```json
{
  "error": "Insufficient permissions",
  "required": {
    "resource": "users",
    "action": "read"
  },
  "message": "API key does not have 'read' permission for 'users'"
}
```

### 400 Bad Request

Invalid request parameters or query.

```json
{
  "error": "Query execution failed"
}
```

## Best Practices

1. **Principle of Least Privilege**: Only grant the minimum permissions required
2. **Use Read-Only Keys**: For reporting and monitoring, use read-only scopes
3. **Rotate Keys Regularly**: Set expiration dates and rotate keys periodically
4. **Secure Storage**: Store API keys in environment variables or secret managers
5. **Monitor Usage**: Check `last_used_at` timestamps to identify unused keys
6. **Name Keys Descriptively**: Use names like "Production Mobile App" or "Analytics Dashboard"

## Security Considerations

- API keys are hashed using bcrypt before storage
- Only shown once upon creation
- Automatic expiration support
- Last usage tracking for auditing
- System tables are protected from API key access
- Dangerous SQL operations (DROP, ALTER, etc.) are blocked

## Rate Limiting

Currently, rate limiting is disabled for testing. In production, implement appropriate rate limits per API key to prevent abuse.

## Examples by Use Case

### Read-Only Analytics Dashboard

Scopes:
- `users:read`
- `applications:read`
- `deployments:read`
- `database:read`

### Mobile App Backend

Scopes:
- `users:read`, `users:update`
- `applications:read`
- `database:read`

### CI/CD Pipeline

Scopes:
- `applications:read`, `applications:update`
- `deployments:create`, `deployments:read`

### Admin Tool

Scopes:
- All resources: `create`, `read`, `update`, `delete`