Skip to main content

​
API Authentication

Conto supports multiple authentication methods for different use cases.

​
Authentication Methods

MethodUse CaseKey Format
SessionDashboard (browser)HTTP-only cookie
SDK KeyAgent paymentsconto_agent_xxx...
API KeyProgrammatic accessconto_xxx...

​
SDK Keys (Agent Authentication)

For AI agents making payments, use SDK keys: 
curl -X POST https://conto.finance/api/sdk/payments/request \
  -H "Authorization: Bearer conto_agent_abc123..." \
  -H "Content-Type: application/json" \
  -d '{"amount": 100, "recipientAddress": "0x..."}'

​
Generate SDK Key

curl -X POST https://conto.finance/api/agents/{agentId}/sdk-keys \
  -H "Authorization: Bearer $CONTO_API_KEY" \
  -d '{"name": "Production Key", "expiresInDays": 90}'

​
SDK Key Scopes

ScopeDescription
payments:requestRequest payment authorization
payments:executeExecute approved payments
payments:statusCheck payment status

​
API Keys (Organization Authentication)

For full platform access, use organization API keys: 
curl https://conto.finance/api/agents \
  -H "Authorization: Bearer conto_abc123..."

​
Create API Key

curl -X POST https://conto.finance/api/api-keys \
  -H "Authorization: Bearer $CONTO_API_KEY" \
  -d '{
    "name": "Production Integration",
    "scopePreset": "STANDARD",
    "expiresInDays": 90
  }'

​
Scope Presets

PresetDescription
READ_ONLYRead access to all resources
STANDARDFull read/write except team management
ADMINFull access including team management

​
Available Scopes

ScopeDescription
agents:readRead agent data
agents:writeCreate/update agents
wallets:readRead wallet data
wallets:writeCreate/fund wallets
transactions:readRead transactions
transactions:writeCreate transactions
policies:readRead policies
policies:writeCreate/update policies
counterparties:readRead counterparties
counterparties:writeManage counterparties
alerts:readRead alerts
alerts:writeManage alerts
analytics:readRead analytics
audit:readRead audit logs
team:readRead team members
team:writeManage team members
adminFull access

​
Error Responses

StatusCodeDescription
401AUTH_FAILEDInvalid or expired key
403INSUFFICIENT_SCOPEKey lacks required scope
429RATE_LIMITEDToo many requests
{
  "error": "Authentication failed",
  "code": "AUTH_FAILED"
}

​
Rate Limits

Endpoint TypeLimit
SDK Payments60/minute per agent
SDK Read120/minute per agent
API Write100/minute per user
API Read100/minute per user
Rate limit headers: 
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 2024-01-15T10:01:00.000Z
Retry-After: 30

​
Best Practices

Never hardcode API keys:
const apiKey = process.env.CONTO_API_KEY;
Set expiration dates and rotate keys periodically.
Only request the scopes you need:
{
  "name": "Analytics Reader",
  "scopes": ["analytics:read", "transactions:read"]
}