Secure Tool API Reference

Authentication Model

Secure tools use a two-tier authentication model based on caller origin:

The installId is an opaque, unguessable identifier generated by the ORC on purchase. It serves as a bearer token for consumer-originated calls. Reject requests with unknown installId values with HTTP 403.

POST /install

Called by the ORC when a user purchases the tool. Register the installation so subsequent configure/execute calls can be validated.

Request

POST {baseUrl}/install
Content-Type: application/json
X-Daisi-Auth: {sharedSecret}

{
  "installId": "inst-260215143022-abcdef",
  "toolId": "weather-lookup",
  "bundleInstallId": "binst-260215143022-shared"
}

Request Fields

Response

{ "success": true }

POST /uninstall

Called by the ORC when a purchase is deactivated (subscription expired, cancelled, etc.). Clean up stored data for this installation.

Request

POST {baseUrl}/uninstall
Content-Type: application/json
X-Daisi-Auth: {sharedSecret}

{
  "installId": "inst-260215143022-abcdef"
}

Response

{ "success": true }

POST /configure

Called directly by the Manager UI when a user saves their setup data (API keys, credentials). No ORC relay.

Request

POST {baseUrl}/configure
Content-Type: application/json

{
  "installId": "inst-260215143022-abcdef",
  "toolId": "weather-lookup",
  "setupValues": {
    "apiKey": "sk-...",
    "region": "US"
  }
}

Request Fields

Response

// Success
{ "success": true }

// Error
{ "success": false, "error": "Invalid API key format" }

POST /execute

Called directly by consumer hosts when the AI invokes the tool during inference. The request contains a sessionId instead of an installId. Your server must validate the session by calling the ORC validation endpoint before executing.

Request

POST {baseUrl}/execute
Content-Type: application/json

{
  "sessionId": "sess-260218120000-xyz789",
  "toolId": "weather-lookup",
  "parameters": [
    { "name": "city", "value": "San Francisco" },
    { "name": "units", "value": "fahrenheit" }
  ]
}

Request Fields

Response

// Success
{
  "success": true,
  "output": "72 F, Sunny with clear skies",
  "outputFormat": "plaintext",
  "outputMessage": "Current weather for San Francisco"
}

// Error
{
  "success": false,
  "errorMessage": "API rate limit exceeded. Please try again in 60 seconds."
}

Response Fields

POST /auth/status

Called by the Manager UI to check whether an OAuth connection is active for a given installation and service. Only relevant for setup parameters with type oauth.

Request

POST {baseUrl}/auth/status
Content-Type: application/json

{
  "installId": "inst-260215143022-abcdef",
  "service": "office365"
}

Request Fields

Response

{
  "connected": true,
  "serviceName": "office365",
  "userLabel": "Connected"
}

Response Fields

POST /api/secure-tools/validate ORC Endpoint

This is an ORC endpoint that your provider server calls to validate a session before executing a tool. It resolves the ephemeral sessionId to the permanent installId associated with the purchase.

Request

POST {OrcValidationUrl}/api/secure-tools/validate
Content-Type: application/json
X-Daisi-Auth: {sharedSecret}

{
  "sessionId": "sess-260218120000-xyz789",
  "toolId": "weather-lookup"
}

Request Fields

Request Headers

Response

// Valid session
{
  "valid": true,
  "installId": "inst-260215143022-abcdef",
  "bundleInstallId": "binst-260215143022-shared"
}

// Invalid session
{
  "valid": false,
  "error": "Session not found or expired"
}

Response Fields

ExecutionCreditCost on MarketplaceItemInfo

Marketplace items that charge per execution include an ExecutionCreditCost field in their item metadata. This value represents the number of credits deducted from the consumer each time the tool is invoked.

Consumers can check this field before invoking a tool to understand the cost. Hosts include this information when presenting available tools to the AI.

Error Handling

Providers should handle errors gracefully:

Setup Parameter Types

When defining setup parameters in the marketplace item, choose the appropriate type for the Manager UI:

OAuth-Specific Fields

When using the oauth type, two additional fields are required on the setup parameter: