first commit

Made-with: Cursor
2026-02-28 02:17:55 +00:00
commit 41f6ae916f
92 changed files with 12332 additions and 0 deletions
--- a/internal/api/openapi/specs/apikeys.json
+++ b/internal/api/openapi/specs/apikeys.json
@@ -0,0 +1,101 @@
+{
+  "paths": {
+    "/api-keys": {
+      "post": {
+        "tags": ["API Keys"],
+        "summary": "Create a new API key",
+        "description": "Creates a new API key with specified scopes for agent/programmatic access. The raw token is returned only once in the response.",
+        "operationId": "createApiKey",
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "required": ["name", "scopes"],
+                "properties": {
+                  "name": { "type": "string", "example": "My agent key" },
+                  "scopes": {
+                    "type": "object",
+                    "description": "Permission scopes for the API key",
+                    "properties": {
+                      "calendars": { "type": "array", "items": { "type": "string", "enum": ["read", "write"] } },
+                      "events": { "type": "array", "items": { "type": "string", "enum": ["read", "write"] } },
+                      "contacts": { "type": "array", "items": { "type": "string", "enum": ["read", "write"] } },
+                      "availability": { "type": "array", "items": { "type": "string", "enum": ["read"] } },
+                      "booking": { "type": "array", "items": { "type": "string", "enum": ["write"] } }
+                    },
+                    "example": {
+                      "calendars": ["read", "write"],
+                      "events": ["read", "write"],
+                      "contacts": ["read"],
+                      "availability": ["read"]
+                    }
+                  }
+                }
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "API key created (token shown only once)",
+            "content": {
+              "application/json": {
+                "schema": { "$ref": "#/components/schemas/APIKeyResponse" }
+              }
+            }
+          },
+          "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
+          "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
+        }
+      },
+      "get": {
+        "tags": ["API Keys"],
+        "summary": "List API keys",
+        "description": "Returns all API keys for the authenticated user. Tokens are never returned in list responses.",
+        "operationId": "listApiKeys",
+        "responses": {
+          "200": {
+            "description": "List of API keys",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "required": ["items", "page"],
+                  "properties": {
+                    "items": { "type": "array", "items": { "$ref": "#/components/schemas/APIKeyResponse" } },
+                    "page": { "$ref": "#/components/schemas/PageInfo" }
+                  }
+                }
+              }
+            }
+          },
+          "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
+        }
+      }
+    },
+    "/api-keys/{id}": {
+      "delete": {
+        "tags": ["API Keys"],
+        "summary": "Revoke an API key",
+        "description": "Revokes the specified API key, preventing further use.",
+        "operationId": "revokeApiKey",
+        "parameters": [
+          {
+            "name": "id",
+            "in": "path",
+            "required": true,
+            "schema": { "type": "string", "format": "uuid" },
+            "description": "API key ID"
+          }
+        ],
+        "responses": {
+          "200": { "description": "API key revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OkResponse" } } } },
+          "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
+          "404": { "description": "API key not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
+        }
+      }
+    }
+  }
+}