Skip to main content
Secrets are encrypted environment variables passed to agents at runtime. They allow you to store sensitive data like API keys without hardcoding them in your agent code.

​
Base URL

All secret endpoints are under: 
https://api.superserve.ai/v1/agents/{agent_id}/secrets

​
Set Secrets

Set one or more secrets for an agent. This replaces existing values for the specified keys. 
PATCH /v1/agents/{agent_id}/secrets
Authorization: Bearer YOUR_API_TOKEN
Content-Type: application/json
Path Parameters:
​
agent_id
string
required
Agent ID (e.g., agt_abc123)
Request Body:
​
secrets
object
required
Key-value pairs of secrets to set. Keys are environment variable names, values are the secret values.
Example Request: 
{
  "secrets": {
    "ANTHROPIC_API_KEY": "sk-ant-...",
    "DATABASE_URL": "postgresql://..."
  }
}
Response:
​
keys
string[]
required
Array of all secret keys now set for this agent (not just the ones you added)
Example Response: 
{
  "keys": ["ANTHROPIC_API_KEY", "DATABASE_URL", "EXISTING_SECRET"]
}
Secret values are write-only. You cannot retrieve secret values via the API — only the keys are returned.

​
List Secret Keys

Retrieve the names of all secrets set for an agent. 
GET /v1/agents/{agent_id}/secrets
Authorization: Bearer YOUR_API_TOKEN
Path Parameters:
​
agent_id
string
required
Agent ID (e.g., agt_abc123)
Response:
​
keys
string[]
required
Array of secret key names
Example Response: 
{
  "keys": ["ANTHROPIC_API_KEY", "DATABASE_URL"]
}

​
Delete Secret

Remove a specific secret from an agent. 
DELETE /v1/agents/{agent_id}/secrets/{key}
Authorization: Bearer YOUR_API_TOKEN
Path Parameters:
​
agent_id
string
required
Agent ID (e.g., agt_abc123)
​
key
string
required
Secret key to delete (URL-encoded)
Response:
​
keys
string[]
required
Array of remaining secret keys after deletion
Example Response: 
{
  "keys": ["DATABASE_URL"]
}

​
Required Secrets

When you deploy an agent, it may declare required secrets in its configuration. These are returned in the agent’s required_secrets field: 
{
  "id": "agt_abc123",
  "name": "my-agent",
  "required_secrets": ["ANTHROPIC_API_KEY"],
  ...
}
You must set all required secrets before creating sessions with the agent. Runs will fail if required secrets are missing.

​
Using Secrets in Agent Code

Secrets are injected as environment variables: 
// In your agent code
const apiKey = process.env.ANTHROPIC_API_KEY

if (!apiKey) {
  throw new Error('ANTHROPIC_API_KEY is required')
}

​
CLI Usage

You can also manage secrets via the CLI: 
# Set secrets interactively
superserve secrets set my-agent

# Set from a file
superserve secrets set my-agent --env-file .env

# List secret keys
superserve secrets list my-agent

# Delete a secret
superserve secrets delete my-agent ANTHROPIC_API_KEY

​
Security Best Practices

Never commit secrets

Add .env files to .gitignore and use the CLI or API to set secrets

Rotate regularly

Update secrets periodically using superserve secrets set

Principle of least privilege

Only grant agents access to the secrets they need

Use strong values

Generate cryptographically secure API keys and tokens

​
Error Responses

​
status
number
HTTP status code
​
detail
string
Error message
​
details
object
Additional error context
Common Errors:
StatusMessage
401Not authenticated
404Agent not found
422Invalid secret format

Build docs developers (and LLMs) love

Get started for freeTalk to us