subcent

Agents API

Agents represent AI systems that are authorized to spend from a vault. Each agent receives a unique API key (sc_agent_ prefix) scoped to its vault and governed by its assigned policy.

Register Agent#

POST
/v1/agents

Register a new agent and receive a one-time API key.

Request Body#

| Field | Type | Required | Description | |---|---|---|---| | vault_id | string | Yes | The vault this agent will be authorized to spend from | | label | string | No | Human-readable name for the agent | | framework | string | No | AI framework identifier (e.g., "langchain", "autogpt", "crewai") | | webhook_url | string | No | URL to receive agent-specific webhook notifications |

Example Request#

{
  "vault_id": "550e8400-e29b-41d4-a716-446655440000",
  "label": "Shopping Assistant",
  "framework": "langchain",
  "webhook_url": "https://your-app.com/webhooks/agent-events"
}

Response#

{
  "agent_id": "agt_550e8400-e29b-41d4-a716-446655440000",
  "api_key": "sc_agent_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4",
  "vault_id": "550e8400-e29b-41d4-a716-446655440000",
  "label": "Shopping Assistant",
  "status": "active",
  "created_at": "2025-01-15T10:30:00.000Z"
}
x

The api_key field is returned only once in this response. It is hashed before storage and cannot be retrieved again. Store it securely in your application's secrets manager.

Errors#

| Error Code | Description | |---|---| | vault_not_found | The specified vault does not exist |

Agent API Key#

The returned api_key uses the sc_agent_ prefix and has the following properties:

  • Scoped to a single vault -- it can only request payments from the vault it was registered with
  • Subject to the agent's policy -- every payment is evaluated against the active policy
  • Revocable -- call the DELETE endpoint to permanently revoke access
  • 48 bytes of entropy -- cryptographically random, SHA-256 hashed for storage

Revoke Agent#

DELETE
/v1/agents/:id

Permanently revoke an agent's access.

Revoking an agent immediately invalidates its API key. Any subsequent payment requests from this agent will receive an agent_revoked error. This action is irreversible -- to restore access, register a new agent.

Path Parameters#

| Parameter | Type | Description | |---|---|---| | id | string | The agent ID |

Response#

{
  "agent_id": "agt_550e8400-e29b-41d4-a716-446655440000",
  "status": "revoked"
}

Errors#

| Error Code | Description | |---|---| | agent_not_authorized | No agent exists with the given ID |

!

Revoking an agent does not cancel any payments that are already pending_approval. Those must be individually rejected or will time out according to their policy's timeout_seconds setting.

Agent Statuses#

| Status | Description | |---|---| | active | Agent is operational and can make payment requests | | revoked | Agent access has been permanently revoked |