Secure Tool API Reference
Complete REST API contract for secure tool providers.
Authentication Model
Secure tools use a two-tier authentication model based on caller origin:
| Endpoint | Caller | Auth Method |
|---|---|---|
/install | ORC | X-Daisi-Auth shared secret header |
/uninstall | ORC | X-Daisi-Auth shared secret header |
/configure | Manager UI (direct) | Known installId (registered via /install) |
/execute | Consumer Host (direct) | Known installId (registered via /install) |
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"
}
Request Fields
| Field | Type | Description |
|---|---|---|
installId | string | Opaque identifier for this installation. Store this to validate future requests. |
toolId | string | The tool ID as defined in the marketplace item. |
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
| Field | Type | Description |
|---|---|---|
installId | string | The installation identifier (registered via /install). Validate that this is known. |
toolId | string | The tool ID as defined in the marketplace item. |
setupValues | object | Key-value pairs matching the setup parameters defined in the marketplace item. |
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. No ORC relay.
Request
POST {baseUrl}/execute
Content-Type: application/json
{
"installId": "inst-260215143022-abcdef",
"toolId": "weather-lookup",
"parameters": [
{ "name": "city", "value": "San Francisco" },
{ "name": "units", "value": "fahrenheit" }
]
}
Request Fields
| Field | Type | Description |
|---|---|---|
installId | string | The installation identifier (registered via /install). Validate that this is known. |
toolId | string | The tool ID as defined in the marketplace item. |
parameters | array | Name/value pairs provided by the AI, matching the call parameters defined in the marketplace item. |
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
| Field | Type | Description |
|---|---|---|
success | bool | Whether the tool executed successfully. |
output | string | The tool's output, returned to the AI. |
outputFormat | string | Format of the output: plaintext, json, markdown, html, or base64. |
outputMessage | string? | Optional message to accompany the output for additional context. |
errorMessage | string? | Error description when success is false. |
Error Handling
Providers should handle errors gracefully:
| Scenario | Recommended Response |
|---|---|
Missing or invalid X-Daisi-Auth (install/uninstall) | HTTP 401 Unauthorized |
Unknown installId (configure/execute) | HTTP 403 Forbidden with descriptive error |
| Installation not configured | HTTP 200 with success: false and descriptive error message |
| Invalid parameters | HTTP 200 with success: false and descriptive error message |
| External API failure | HTTP 200 with success: false and error message. Do not return HTTP 500 for expected failures. |
| Unexpected server error | HTTP 500 (the host will return a generic "Provider returned HTTP 500" error) |
Setup Parameter Types
When defining setup parameters in the marketplace item, choose the appropriate type for the Manager UI:
| Type | UI Rendering | Use Case |
|---|---|---|
text | Standard text input | Region names, identifiers, non-sensitive strings |
password | Password input (masked) | Passwords, tokens |
apikey | Password input (masked) | API keys, secret keys |
url | URL text input | Endpoint URLs, webhook URLs |
json | Multiline textarea (monospace) | JSON configuration objects |