Appearance
Secrets API Reference
API endpoints for secrets detection, policy configuration, and audit.
IDE and agent traffic that should be scanned before it reaches an LLM is usually configured as a proxy to GhostAI’s OpenAI- or Anthropic-compatible endpoints, not through this REST API. Use Settings → Keys → Connect a tool in the app, or the AI tool setup guide, for step-by-step configuration.
POST /api/detect/secrets
Scan text for secrets (API keys, tokens, credentials, database URLs, private keys).
Request
POST /api/detect/secrets
Content-Type: application/json
Authorization: Bearer <token> (optional)json
{
"text": "My API key is sk-proj-abc123xyz789... and DB url is postgres://user:secret@localhost/db",
"filename": ".env"
}| Field | Type | Required | Description |
|---|---|---|---|
text | string | Yes | Text to scan for secrets |
filename | string | No | Optional filename for context (e.g., .env enables env parsing) |
Response
json
{
"secrets": [
{
"secret_type": "openai_key",
"masked_value": "sk-p****xyz789",
"start": 15,
"end": 48,
"line_number": 1,
"confidence": 0.9,
"severity": "high",
"context": "My API key is sk-proj-abc123xyz789..."
},
{
"secret_type": "database_url",
"masked_value": "postg****ocalhost/db",
"start": 55,
"end": 85,
"line_number": 1,
"confidence": 0.95,
"severity": "critical",
"context": "DB url is postgres://user:secret@localhost/db"
}
],
"count": 2,
"high_risk_count": 2
}| Field | Type | Description |
|---|---|---|
secrets | array | Detected secrets with masked values |
count | integer | Total number of secrets found |
high_risk_count | integer | Count of high-confidence (≥0.90) secrets |
POST /v1/messages (Anthropic Compat)
Anthropic Messages API endpoint compatible with Claude Code, Cline, Continue (Anthropic mode), and Aider. All user and system message content is scanned for secrets before forwarding to the model. Policy (warn/block/redact) and secret budget apply.
What's New
- Response secrets scanning: When
scan_responsesis enabled, LLM responses are scanned for secrets and redacted before reaching the client. - Streaming detokenization: PII tokens in streamed responses are now properly restored, even when a token spans multiple SSE chunks.
- Audit logging: All requests (including anonymous/unauthenticated) are now logged to the audit trail.
Request
POST /v1/messages
Content-Type: application/json
x-api-key: gst_<api_key>
anthropic-version: 2023-06-01json
{
"model": "claude-3-5-sonnet-20241022",
"max_tokens": 1024,
"messages": [
{
"role": "user",
"content": "Review this config: API_KEY=sk-abc123..."
}
]
}Response (success)
Secrets are redacted (in redact mode) before the request reaches Anthropic. The response includes GhostAI metadata when secrets were detected:
json
{
"id": "msg_...",
"type": "message",
"role": "assistant",
"content": [...],
"model": "claude-3-5-sonnet-20241022",
"stop_reason": "end_turn",
"usage": {...}
}Response headers may include x-ghost-secrets-detected when secrets were found and handled.
Response (blocked)
When policy is block and secrets are detected:
json
{
"error": {
"message": "Request blocked: 2 secret(s) detected. Remove secrets before sending to the AI provider.",
"type": "secrets_blocked",
"code": "secrets_detected"
}
}HTTP status: 400 Bad Request
GET /api/settings/secrets-policy
Get the current secrets protection policy and settings.
Request
GET /api/settings/secrets-policy
Authorization: Bearer <token>Response
json
{
"policy": "redact",
"enabled": true,
"scan_responses": true,
"max_secrets_per_request": 5,
"enable_entropy_detection": true,
"entropy_threshold": 4.5,
"description": "Detect secrets and replace them with reversible tokens before forwarding to the AI. Default and recommended mode."
}| Field | Type | Description |
|---|---|---|
policy | string | warn, block, or redact |
enabled | boolean | Whether secrets detection is enabled |
scan_responses | boolean | Whether to scan LLM responses for secrets |
max_secrets_per_request | integer | Secret budget before policy escalation |
enable_entropy_detection | boolean | Enable high-entropy string detection |
entropy_threshold | number | Bits per character threshold (2.0–6.0) |
description | string | Human-readable policy description |
PUT /api/settings/secrets-policy
Update secrets protection policy settings.
Request
PUT /api/settings/secrets-policy
Content-Type: application/json
Authorization: Bearer <token>json
{
"policy": "block",
"enabled": true,
"scan_responses": true,
"max_secrets_per_request": 10,
"enable_entropy_detection": true,
"entropy_threshold": 4.5
}| Field | Type | Required | Description |
|---|---|---|---|
policy | string | No | warn, block, or redact |
enabled | boolean | No | Enable/disable secrets detection |
scan_responses | boolean | No | Scan LLM responses |
max_secrets_per_request | integer | No | Must be ≥ 1 |
enable_entropy_detection | boolean | No | Enable entropy detection |
entropy_threshold | number | No | Must be between 2.0 and 6.0 |
All fields are optional; only provided fields are updated.
Response
Same structure as GET response with updated values.
Validation Errors
max_secrets_per_request must be >= 1— HTTP 422entropy_threshold must be between 2.0 and 6.0— HTTP 422
GET /api/secrets/audit
Paginated list of secret detection events.
Request
GET /api/secrets/audit?limit=50&offset=0
Authorization: Bearer <token>| Query | Type | Default | Description |
|---|---|---|---|
limit | integer | 50 | Page size (1–500) |
offset | integer | 0 | Pagination offset |
Response
json
{
"items": [
{
"id": "det-001",
"secret_type": "aws_access_key",
"masked_value": "AKIA****abcd",
"severity": "high",
"source_tool": "cursor",
"action": "blocked",
"detected_at": "2025-03-11T14:30:00Z",
"context": "AWS_ACCESS_KEY_ID=AKIA..."
},
{
"id": "det-002",
"secret_type": "github_token",
"masked_value": "ghp_****xyz",
"severity": "high",
"source_tool": "cursor",
"action": "warned",
"detected_at": "2025-03-11T14:25:00Z",
"context": "GITHUB_TOKEN=ghp_..."
}
],
"total": 2,
"limit": 50,
"offset": 0
}| Field | Type | Description |
|---|---|---|
items | array | Detection records |
total | integer | Total count |
limit | integer | Page size |
offset | integer | Offset used |
GET /api/secrets/audit/summary
Aggregate statistics for secret detections.
Request
GET /api/secrets/audit/summary
Authorization: Bearer <token>Response
json
{
"total_detected": 15,
"by_type": {
"aws_access_key": 3,
"github_token": 5,
"openai_key": 4,
"database_url": 2,
"generic_api_key": 1
},
"by_tool": {
"cursor": 8,
"chat": 5,
"claude_code": 2
},
"by_action": {
"blocked": 6,
"warned": 4,
"redacted": 5
}
}GET /api/secrets/audit/rotation-needed
Secrets detected in warn mode that should be rotated (exposed but allowed through).
Request
GET /api/secrets/audit/rotation-needed
Authorization: Bearer <token>Response
json
{
"items": [
{
"id": "det-002",
"secret_type": "github_token",
"masked_value": "ghp_****xyz",
"severity": "high",
"source_tool": "cursor",
"detected_at": "2025-03-11T14:25:00Z"
}
],
"total": 1
}Related Endpoints
- POST /v1/chat/completions — OpenAI-compatible chat; secrets protection applies to user messages. See OpenAI Compatible API.
- POST /api/detect — PII detection (complementary to secrets). See Detection API.