📡 SDKs

REST API Reference

Complete HTTP API reference. Integrate from any language, platform, or runtime.

Base URLhttps://api.agentsecretstore.com/v1

Authentication

All API requests require a Bearer token in the Authorization header. You can use either your master agent key or a scoped token.

Shell

# All requests require Authorization header
curl -H "Authorization: Bearer ass_live_your_key_here" \
     https://api.agentsecretstore.com/v1/secrets

Path encoding

Secret paths contain forward slashes. URL-encode them when using in path segments: production/openai/api-key → production%2Fopenai%2Fapi-key. Query parameter values are automatically decoded.

POST/secrets

Create a secret

Create a new secret. Returns 409 if the path already exists.

Shell

curl -X POST https://api.agentsecretstore.com/v1/secrets \
  -H "Authorization: Bearer $ASS_AGENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "path": "production/openai/api-key",
    "value": "sk-proj-abc123...",
    "tier": "sensitive",
    "description": "OpenAI production key",
    "tags": {"team": "ml", "env": "prod"}
  }'

# Response 201 Created:
{
  "path": "production/openai/api-key",
  "version": 1,
  "tier": "sensitive",
  "created_at": "2025-01-15T10:30:00Z"
}

GET/secrets/:path

Get a secret

Retrieve a secret value by path. Path must be URL-encoded.

Shell

curl https://api.agentsecretstore.com/v1/secrets/production%2Fopenai%2Fapi-key \
  -H "Authorization: Bearer $ASS_AGENT_KEY"

# Response 200 OK:
{
  "path": "production/openai/api-key",
  "value": "sk-proj-abc123...",
  "version": 1,
  "tier": "sensitive",
  "description": "OpenAI production key",
  "tags": {"team": "ml", "env": "prod"},
  "created_at": "2025-01-15T10:00:00Z",
  "updated_at": "2025-01-15T10:00:00Z",
  "accessed_at": "2025-01-15T10:30:00Z",
  "expires_at": null
}

Get a specific version

Shell

# Get a specific version
curl "https://api.agentsecretstore.com/v1/secrets/production%2Fopenai%2Fapi-key?version=1" \
  -H "Authorization: Bearer $ASS_AGENT_KEY"

GET/secrets

List secrets

List secret metadata in a namespace. Values are never returned in list responses.

Shell

curl "https://api.agentsecretstore.com/v1/secrets?namespace=production%2Fopenai&limit=50" \
  -H "Authorization: Bearer $ASS_AGENT_KEY"

# Response 200 OK:
{
  "items": [
    {
      "path": "production/openai/api-key",
      "version": 1,
      "tier": "sensitive",
      "updated_at": "2025-01-15T10:00:00Z"
    }
  ],
  "total": 1,
  "next_cursor": null
}

PUT/secrets/:path

Update a secret

Update an existing secret. Creates a new version. Path must be URL-encoded.

Shell

curl -X PUT https://api.agentsecretstore.com/v1/secrets/production%2Fopenai%2Fapi-key \
  -H "Authorization: Bearer $ASS_AGENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "value": "sk-proj-updated456...",
    "tier": "sensitive",
    "description": "Updated OpenAI key",
    "tags": {"team": "ml", "env": "prod", "rotated": "true"}
  }'

# Response 200 OK:
{
  "path": "production/openai/api-key",
  "version": 2,
  "updated_at": "2025-01-15T11:00:00Z"
}

DELETE/secrets/:path

Delete a secret

Soft delete (default) or hard delete with ?permanent=true.

Shell

# Soft delete (recoverable for 30 days)
curl -X DELETE https://api.agentsecretstore.com/v1/secrets/staging%2Fopenai%2Ftest-key \
  -H "Authorization: Bearer $ASS_AGENT_KEY"

# Hard delete (permanent)
curl -X DELETE "https://api.agentsecretstore.com/v1/secrets/staging%2Fopenai%2Ftest-key?permanent=true" \
  -H "Authorization: Bearer $ASS_AGENT_KEY"

# Response 204 No Content

POST/secrets/:path/rotate

Rotate a secret

Rotate to a new value. Optionally keep old version readable for a grace period.

Shell

curl -X POST https://api.agentsecretstore.com/v1/secrets/production%2Fopenai%2Fapi-key/rotate \
  -H "Authorization: Bearer $ASS_AGENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "new_value": "sk-proj-rotated789...",
    "grace_period_seconds": 300
  }'

# Response 200 OK:
{
  "path": "production/openai/api-key",
  "old_version": 1,
  "new_version": 2,
  "old_expires_at": "2025-01-15T10:35:00Z"
}

POST/tokens

Create a scoped token

Issue a scoped token. May return 202 if approval is required.

Shell

curl -X POST https://api.agentsecretstore.com/v1/tokens \
  -H "Authorization: Bearer $ASS_AGENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "scope": "secrets:read:production/openai/*",
    "ttl_seconds": 3600,
    "description": "Inference agent token",
    "allowed_ips": ["10.0.1.50"],
    "max_uses": null
  }'

# Response 201 Created (auto-approved):
{
  "value": "ast_tok_abc123...",
  "scope": "secrets:read:production/openai/*",
  "ttl_seconds": 3600,
  "expires_at": "2025-01-15T11:30:00Z",
  "approval_status": "approved",
  "approval_request_id": null
}

# Response 202 Accepted (approval required):
{
  "approval_status": "pending",
  "approval_request_id": "apr_01HQKM3N...",
  "message": "Approval required. Notified 1 approver(s).",
  "approve_url": "https://agentsecretstore.com/approvals/apr_01HQKM3N..."
}

GET/POST/approvals/:id

Approval management

Check, approve, or deny a pending approval request.

Shell

# Check approval status
curl https://api.agentsecretstore.com/v1/approvals/apr_01HQKM3N... \
  -H "Authorization: Bearer $ASS_AGENT_KEY"

# Approve a request
curl -X POST https://api.agentsecretstore.com/v1/approvals/apr_01HQKM3N.../approve \
  -H "Authorization: Bearer $ASS_AGENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"comment": "Approved for batch run #4821"}'

# Deny a request
curl -X POST https://api.agentsecretstore.com/v1/approvals/apr_01HQKM3N.../deny \
  -H "Authorization: Bearer $ASS_AGENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"reason": "Unexpected access pattern"}'

GET/audit

Audit log

Paginated audit events. Filter by namespace, actor, type, or date range.

Shell

curl "https://api.agentsecretstore.com/v1/audit?limit=100&namespace=production" \
  -H "Authorization: Bearer $ASS_AGENT_KEY"

# Response 200 OK:
{
  "events": [
    {
      "id": "evt_01HQKM3N...",
      "type": "secret.read",
      "path": "production/openai/api-key",
      "actor": "token:ast_tok_abc123",
      "actor_description": "Inference agent token",
      "ip": "10.0.1.50",
      "user_agent": "agentsecretstore-python/1.0.0",
      "timestamp": "2025-01-15T10:30:00Z",
      "success": true
    }
  ],
  "next_cursor": "eyJpZCI6ICJl..."
}

Error codes

HTTP Status	Error Code	Meaning
200	ok	Success
201	created	Secret or token created successfully
202	pending	Approval required — check approval_request_id
204	no_content	Delete successful
400	invalid_request	Malformed request body or invalid parameters
401	unauthorized	Missing or invalid agent key / token
403	permission_denied	Token scope does not cover requested path
404	not_found	Secret path does not exist
409	conflict	Secret already exists (use PUT to update)
422	validation_error	Request schema validation failed
429	rate_limited	Too many requests — check Retry-After header
500	internal_error	Server error — retry with exponential backoff

Error response format

JSON

# Error response format:
{
  "error": {
    "code": "permission_denied",
    "message": "Token scope 'secrets:read:production/openai/*' does not cover path 'production/stripe/api-key'",
    "path": "production/stripe/api-key",
    "required_scope": "secrets:read:production/stripe/*"
  }
}

Rate limits

Free

100 req/min

Pro

1,000 req/min

Enterprise

Custom

Rate limit headers: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset. When limited, check the Retry-After header.