{
  "service": {
    "name": "TicoQuickBooks",
    "version": "0.1.0",
    "base_url": "https://quickbooks.ticosync.com",
    "description": "QuickBooks OAuth and token lifecycle service for multiple named company connections."
  },
  "machine_readable_documents": [
    {
      "name": "public_api_document",
      "format": "json",
      "url": "https://quickbooks.ticosync.com/static/api-docs.json"
    },
    {
      "name": "openapi",
      "format": "openapi-json",
      "url": "https://quickbooks.ticosync.com/openapi.json"
    }
  ],
  "authentication": {
    "protected_endpoints": {
      "type": "api_key",
      "header": "X-API-Key",
      "query_parameter": "api_key",
      "environment_variable_name": "TICOQUICKBOOKS_API_KEY"
    }
  },
  "oauth_rules": {
    "sandbox_detection": "If the company_key or company_name contains the substring 'sandbox', the service uses QUICKBOOKS_SANDBOX_CLIENT_ID and QUICKBOOKS_SANDBOX_CLIENT_SECRET.",
    "callback_url": "https://quickbooks.ticosync.com/oauth/callback"
  },
  "endpoints": [
    {
      "name": "health",
      "method": "GET",
      "path": "/health",
      "auth_required": false,
      "description": "Returns a basic health payload.",
      "response_example": {
        "status": "ok"
      }
    },
    {
      "name": "oauth_start",
      "method": "GET",
      "path": "/oauth/start/{company_key}",
      "auth_required": false,
      "description": "Starts a QuickBooks OAuth flow for a company key.",
      "path_params": [
        {
          "name": "company_key",
          "type": "string",
          "required": true
        }
      ],
      "query_params": [
        {
          "name": "company_name",
          "type": "string",
          "required": false
        }
      ]
    },
    {
      "name": "oauth_callback",
      "method": "GET",
      "path": "/oauth/callback",
      "auth_required": false,
      "description": "Completes the QuickBooks OAuth callback and stores tokens.",
      "query_params": [
        {
          "name": "code",
          "type": "string",
          "required": true
        },
        {
          "name": "state",
          "type": "string",
          "required": true
        },
        {
          "name": "realmId",
          "type": "string",
          "required": false
        }
      ]
    },
    {
      "name": "get_token",
      "method": "GET",
      "path": "/api/token/{company_key}",
      "auth_required": true,
      "description": "Returns a valid QuickBooks access token for a company key and refreshes it if needed.",
      "path_params": [
        {
          "name": "company_key",
          "type": "string",
          "required": true
        }
      ],
      "response_fields": [
        "company_key",
        "company_name",
        "realm_id",
        "access_token",
        "access_token_expires_at",
        "refresh_token_expires_at",
        "updated_at",
        "last_refresh_at",
        "uses_sandbox_credentials"
      ]
    },
    {
      "name": "force_refresh_token",
      "method": "POST",
      "path": "/api/token/{company_key}/refresh",
      "auth_required": true,
      "description": "Forces a QuickBooks token refresh for a company key."
    },
    {
      "name": "get_connection_metadata",
      "method": "GET",
      "path": "/api/connections/{company_key}",
      "auth_required": true,
      "description": "Returns non-secret metadata for a stored company connection."
    },
    {
      "name": "list_connections_placeholder",
      "method": "GET",
      "path": "/api/connections",
      "auth_required": true,
      "description": "Placeholder endpoint describing connection access behavior."
    }
  ]
}