Cloud REST API Reference

The AgentSecrets Cloud REST API provides HTTP interfaces for credential resolution, headless environment delivery, and data plane liveness monitoring.

---

Base Service URLs

---

1Outbound Credential Resolution

Resolves placeholder credential handles (AS_SECRET_KEY), injects real credentials over outbound TLS 1.3, and returns a sanitized response.

Endpoint

POST /v1/resolve

Headers

Request Body Schema

{
  "target_url": "https://api.stripe.com/v1/charges",
  "method": "POST",
  "headers": {
    "Authorization": "Bearer AS_SECRET_STRIPE_KEY",
    "Content-Type": "application/x-www-form-urlencoded"
  },
  "body": "amount=2000&currency=usd&source=tok_visa"
}

Response (200 OK)

{
  "status_code": 200,
  "headers": {
    "Content-Type": "application/json",
    "Request-Id": "req_12345"
  },
  "body": "{\"id\": \"ch_12345\", \"amount\": 2000, \"status\": \"succeeded\"}",
  "redacted": false
}

Error Responses

401 Unauthorized (invalid_token)

{
  "error_code": "invalid_token",
  "message": "Workload token is invalid or expired"
}

403 Forbidden (domain_blocked)

{
  "error_code": "domain_blocked",
  "message": "Target host 'evil-attacker.com' is not permitted by workspace allowlist"
}

---

2Container Environment Ingestion ()

Retrieves scoped environment secrets over TLS for container initialization. Used by agentsecrets env and CI/CD runners.

Endpoint

POST /api/workloads/env/

Headers

Response (200 OK)

{
  "status": "success",
  "workspace_id": "8fa3c012-7b89-4e01-a1b2-c3d4e5f6a7b8",
  "project_id": "1ab4d982-3c4e-5f6a-7b8c-9d0e1f2a3b4c",
  "environment": "production",
  "secrets": {
    "DATABASE_URL": "postgres://user:pass@db.internal:5432/prod",
    "STRIPE_KEY": "sk_live_...",
    "OPENAI_API_KEY": "sk-proj-..."
  }
}

---

3Resolver Health & Liveness Probe

Liveness probe for load balancers and container orchestrators.

Endpoint

GET /healthz

Response (200 OK)

{
  "status": "healthy",
  "service": "agentsecrets-cloud-resolver",
  "timestamp": "2026-08-23T00:00:00Z"
}

---

Python SDK Reference Implementation

Using the official Python SDK with the credential helper:

from agentsecrets import AgentSecrets, credential

secrets = AgentSecrets()

response = secrets.call(
    "https://api.stripe.com/v1/charges",
    method="POST",
    headers={"Authorization": f"Bearer {credential.STRIPE_KEY}"},
    body={"amount": 2000, "currency": "usd"}
)

print("Status:", response.status_code)
print("Data:", response.json())