appserver/API_KEYS.md

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

{
  "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:

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)

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

Response:

{
  "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)

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)

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)

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.

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

403 Forbidden

API key doesn't have required permissions.

{
  "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.

{
  "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