Skip to content

authentication.md

Latest commit

 

History

History
102 lines (72 loc) · 2.1 KB

authentication.md

File metadata and controls

102 lines (72 loc) · 2.1 KB
Raw

Authentication Guide

Overview

The Cloud implements a secure, multi-tenant authentication system using API Keys. This ensures resource isolation, meaning users can only access resources (instances, VPCs, volumes, etc.) that they have created.

User Registration

Before using the API, you must register a new account.

Endpoint

POST /auth/register

Request

{
  "email": "user@example.com",
  "password": "securepassword123",
  "name": "John Doe"
}

Response

{
  "message": "user created successfully",
  "user_id": "550e8400-e29b-41d4-a716-446655440000"
}

Login & API Key Retrieval

After registering, log in to obtain your API Key. This key must be included in all subsequent API requests.

Endpoint

POST /auth/login

Request

{
  "email": "user@example.com",
  "password": "securepassword123"
}

Response

{
  "token": "apk_123456789...", 
  "expires_in": 86400
}

Note: The token field contains your API Key.

Authenticating Requests

All protected API endpoints require the X-API-Key header.

Header Format

X-API-Key: apk_123456789...

Example Request

curl -H "X-API-Key: apk_123456789..." http://localhost:8080/instances

If the key is missing or invalid, the API will return 401 Unauthorized.

WebSocket Authentication

For WebSocket connections (e.g., real-time metrics), the API Key is passed as a query parameter.

URL Structure

ws://localhost:8080/ws?api_key=apk_123456789...

Key Management

Manage Keys

You can list and manage your keys via the /auth/keys endpoints.

  • List Keys: GET /auth/keys
  • Revoke Key: DELETE /auth/keys/:id
  • Rotate Key: POST /auth/keys/rotate

Security Best Practices

  1. Keep your API Key secret: Do not commit it to version control or share it publicly.
  2. Use HTTPS: In production, ensure all API traffic is encrypted.
  3. Rotate Keys Regularly: Periodically rotate your keys using the rotation endpoint to minimize risk.
  4. Revoke Immediately: If a key is compromised, revoke it immediately via the API.