{
  "openapi": "3.1.0",
  "info": {
    "title": "Toknbase API",
    "version": "1.9.0",
    "description": "Zero-trust secrets management REST API. All endpoints require an agent token in the Authorization header.",
    "contact": {
      "name": "Toknbase Support",
      "email": "support@toknbase.net",
      "url": "https://toknbase.net"
    }
  },
  "servers": [
    {
      "url": "https://xi7mc-uaaaa-aaaan-q5raa-cai.raw.icp0.io",
      "description": "Production (ICP Canister)"
    }
  ],
  "security": [{ "BearerAuth": [] }],
  "components": {
    "securitySchemes": {
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "Agent Token (agt_...)",
        "description": "Agent token created in the Toknbase dashboard. Scopes: read_only, read_write, full_access."
      }
    },
    "schemas": {
      "SecretListResponse": {
        "type": "object",
        "properties": {
          "secrets": {
            "type": "array",
            "items": { "type": "string" },
            "description": "Array of accessible secret names (no values)"
          }
        },
        "required": ["secrets"]
      },
      "SecretGetResponse": {
        "type": "object",
        "properties": {
          "name": { "type": "string" },
          "value": { "type": "string", "description": "Plaintext secret value" },
          "environment": { "type": "string" }
        },
        "required": ["name", "value"]
      },
      "SecretCreateRequest": {
        "type": "object",
        "properties": {
          "name": { "type": "string" },
          "value": { "type": "string" },
          "description": { "type": "string" },
          "environment": {
            "type": "string",
            "enum": ["production", "staging", "development"]
          }
        },
        "required": ["name", "value"]
      },
      "SecretCreateResponse": {
        "type": "object",
        "properties": {
          "ok": { "type": "boolean" },
          "id": { "type": "string" }
        },
        "required": ["ok"]
      },
      "SecretUpdateRequest": {
        "type": "object",
        "properties": {
          "value": { "type": "string" }
        },
        "required": ["value"]
      },
      "OkResponse": {
        "type": "object",
        "properties": { "ok": { "type": "boolean" } },
        "required": ["ok"]
      },
      "FolderCreateRequest": {
        "type": "object",
        "properties": {
          "name": { "type": "string" },
          "parentId": { "type": "string" }
        },
        "required": ["name"]
      },
      "FolderListResponse": {
        "type": "object",
        "properties": {
          "folders": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": { "type": "string" },
                "name": { "type": "string" },
                "parentId": { "type": "string" }
              }
            }
          }
        }
      },
      "FolderAssignRequest": {
        "type": "object",
        "properties": {
          "secretId": { "type": "string" },
          "folderId": { "type": "string" }
        },
        "required": ["secretId", "folderId"]
      },
      "ErrorResponse": {
        "type": "object",
        "properties": { "error": { "type": "string" } },
        "required": ["error"]
      }
    },
    "responses": {
      "Unauthorized": {
        "description": "Missing or invalid agent token",
        "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }
      },
      "NotFound": {
        "description": "Resource not found",
        "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }
      },
      "TooManyRequests": {
        "description": "Rate limit exceeded (60 writes per 60 seconds per token)",
        "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }
      }
    }
  },
  "paths": {
    "/api/secret": {
      "get": {
        "operationId": "getSecret",
        "summary": "Get a secret by name",
        "description": "Returns the plaintext value of a single secret accessible by the agent token.",
        "tags": ["Secrets"],
        "parameters": [
          {
            "name": "name",
            "in": "query",
            "required": true,
            "schema": { "type": "string" },
            "description": "Secret name",
            "example": "DATABASE_URL"
          }
        ],
        "responses": {
          "200": { "description": "Secret found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SecretGetResponse" } } } },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "404": { "$ref": "#/components/responses/NotFound" }
        }
      }
    },
    "/api/secrets": {
      "get": {
        "operationId": "listSecrets",
        "summary": "List accessible secret names",
        "description": "Returns all secret names accessible by this token. Values are not included.",
        "tags": ["Secrets"],
        "responses": {
          "200": { "description": "Secret names", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SecretListResponse" } } } },
          "401": { "$ref": "#/components/responses/Unauthorized" }
        }
      },
      "post": {
        "operationId": "createSecret",
        "summary": "Create a new secret",
        "description": "Creates a new secret. Requires read_write or full_access scope.",
        "tags": ["Secrets"],
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SecretCreateRequest" } } } },
        "responses": {
          "200": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SecretCreateResponse" } } } },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "429": { "$ref": "#/components/responses/TooManyRequests" }
        }
      }
    },
    "/api/secrets/{name}": {
      "put": {
        "operationId": "updateSecret",
        "summary": "Update an existing secret",
        "description": "Updates the value of an existing secret. Requires read_write or full_access scope.",
        "tags": ["Secrets"],
        "parameters": [
          { "name": "name", "in": "path", "required": true, "schema": { "type": "string" }, "example": "DATABASE_URL" }
        ],
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SecretUpdateRequest" } } } },
        "responses": {
          "200": { "description": "Updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OkResponse" } } } },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "404": { "$ref": "#/components/responses/NotFound" },
          "429": { "$ref": "#/components/responses/TooManyRequests" }
        }
      },
      "delete": {
        "operationId": "deleteSecret",
        "summary": "Delete a secret",
        "description": "Permanently deletes a secret and its version history. Requires full_access scope.",
        "tags": ["Secrets"],
        "parameters": [
          { "name": "name", "in": "path", "required": true, "schema": { "type": "string" }, "example": "OLD_API_KEY" }
        ],
        "responses": {
          "200": { "description": "Deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OkResponse" } } } },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "404": { "$ref": "#/components/responses/NotFound" },
          "429": { "$ref": "#/components/responses/TooManyRequests" }
        }
      }
    },
    "/api/secrets/export": {
      "get": {
        "operationId": "exportSecrets",
        "summary": "Export all secrets",
        "description": "Returns all accessible secrets with plaintext values. Requires full_access scope. Output is unencrypted — handle with care.",
        "tags": ["Secrets"],
        "responses": {
          "200": { "description": "All secrets", "content": { "application/json": { "schema": { "type": "object", "properties": { "secrets": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "value": { "type": "string" }, "environment": { "type": "string" } } } } } } } } },
          "401": { "$ref": "#/components/responses/Unauthorized" }
        }
      }
    },
    "/api/folders": {
      "get": {
        "operationId": "listFolders",
        "summary": "List all folders",
        "description": "Returns all folders owned by the token's principal.",
        "tags": ["Folders"],
        "responses": {
          "200": { "description": "Folders", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FolderListResponse" } } } },
          "401": { "$ref": "#/components/responses/Unauthorized" }
        }
      },
      "post": {
        "operationId": "createFolder",
        "summary": "Create a folder",
        "description": "Creates a folder for organizing secrets. Requires read_write or full_access scope.",
        "tags": ["Folders"],
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FolderCreateRequest" } } } },
        "responses": {
          "200": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OkResponse" } } } },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "429": { "$ref": "#/components/responses/TooManyRequests" }
        }
      }
    },
    "/api/folders/assign": {
      "post": {
        "operationId": "assignSecretToFolder",
        "summary": "Assign a secret to a folder",
        "description": "Associates a secret with a folder. Requires read_write or full_access scope.",
        "tags": ["Folders"],
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FolderAssignRequest" } } } },
        "responses": {
          "200": { "description": "Assigned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OkResponse" } } } },
          "401": { "$ref": "#/components/responses/Unauthorized" }
        }
      }
    }
  },
  "tags": [
    { "name": "Secrets", "description": "CRUD operations for secrets." },
    { "name": "Folders", "description": "Folder management for organizing secrets." }
  ]
}