Environment Variables API

Environment variables store credentials (API keys, tokens, secrets) that tools need to function. Values are encrypted at rest and scoped per-tool - each tool only receives the secrets declared in its manifest.

Set a Credential

POST /agents/{agent_id}/env-vars

Create or update a single environment variable.

Request:

{
  "key": "WEATHER_API_KEY",
  "value": "wk_abc123..."
}

Key format: uppercase letters, digits, and underscores. Must start with a letter. Max 255 characters. Pattern: ^[A-Z][A-Z0-9_]*$

Value: 1 to 10,000 characters.

Response (201):

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "key": "WEATHER_API_KEY",
  "has_value": true,
  "created_at": "2026-04-01T12:00:00Z",
  "updated_at": "2026-04-01T12:00:00Z"
}

The response never returns the actual value - only has_value: true. If the key already exists, its value is updated.

After setting a credential, Kate automatically refreshes the credential status for any tools that require this key.

Rate limit: 30/minute

Bulk Set Credentials

POST /agents/{agent_id}/env-vars/bulk

Set multiple environment variables at once. Maximum 50 per request.

Request:

{
  "vars": [
    {"key": "WEATHER_API_KEY", "value": "wk_abc123..."},
    {"key": "SEO_API_KEY", "value": "sk_def456..."}
  ]
}

Response (201):

[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "key": "WEATHER_API_KEY",
    "has_value": true,
    "created_at": "2026-04-01T12:00:00Z",
    "updated_at": "2026-04-01T12:00:00Z"
  },
  {
    "id": "660e8400-e29b-41d4-a716-446655440001",
    "key": "SEO_API_KEY",
    "has_value": true,
    "created_at": "2026-04-01T12:00:00Z",
    "updated_at": "2026-04-01T12:00:00Z"
  }
]

Rate limit: 10/minute

List Credentials

GET /agents/{agent_id}/env-vars

List all environment variables for an agent. Values are never returned.

Response:

[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "key": "WEATHER_API_KEY",
    "has_value": true,
    "created_at": "2026-04-01T12:00:00Z",
    "updated_at": "2026-04-01T12:00:00Z"
  },
  {
    "id": "660e8400-e29b-41d4-a716-446655440001",
    "key": "SEO_API_KEY",
    "has_value": true,
    "created_at": "2026-04-01T12:00:00Z",
    "updated_at": "2026-04-01T12:00:00Z"
  }
]

Rate limit: 60/minute

Delete a Credential

DELETE /agents/{agent_id}/env-vars/{key}

Delete an environment variable by its key name.

Response: 204 No Content

After deletion, Kate refreshes credential status for affected tools. Tools that required this key will show pending credentials status.

Error codes:

Rate limit: 30/minute

Authentication

All endpoints require an x-api-key header:

x-api-key: your-api-key

The API key must belong to the agent's owner.

Error Codes

Next Steps

• Tools API Reference - tool endpoints
• Use Marketplace Tools - credential setup walkthrough
• Tool Management - dashboard credential UI