Skip to main content

​
SDK Authentication

The Conto SDK authenticates using agent-specific SDK keys.

​
SDK Keys

SDK keys are scoped to a specific agent and can only perform payment operations. They use the format: 
conto_agent_[64-character-hex-string]
Example: conto_agent_a1b2c3d4e5f6789012345678901234567890abcdef1234567890abcdef12345678

​
Generating SDK Keys

​
Via Dashboard

1

Go to Agent Details

Navigate to Agents and click on your agent.
2

Open SDK Keys Tab

Click the SDK Keys tab.
3

Generate Key

Click Generate New Key and enter a name.
4

Copy the Key

Copy and save the key immediately! It will only be shown once.

​
Via API

curl -X POST https://conto.finance/api/agents/{agentId}/sdk-keys \
  -H "Authorization: Bearer $CONTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production Key",
    "expiresInDays": 90
  }'
Response: 
{
  "id": "key_abc123",
  "key": "conto_agent_abc123def456...",
  "name": "Production Key",
  "expiresAt": "2024-04-15T10:00:00Z"
}

​
Using SDK Keys

​
Initialize the SDK

import { Conto } from '@conto/sdk';

const conto = new Conto({
  apiKey: 'conto_agent_abc123...',  // Your SDK key
});
.env
CONTO_API_KEY=conto_agent_abc123def456...

const conto = new Conto({
  apiKey: process.env.CONTO_API_KEY!,
});

​
SDK Scopes

SDK keys are granted specific scopes that control access to different endpoints. Scopes are configured when generating an SDK key.

​
Default Scopes

These scopes are included by default:
ScopeDescription
payments:requestRequest payment authorization
payments:executeExecute approved payments

​
Additional Scopes

These scopes can be added for broader access:
ScopeDescription
payments:confirmConfirm external wallet payments
wallets:readView wallet balances and limits
transactions:readView transaction history
transactions:writeRetry failed transactions
policies:readView policies governing the agent
policies:exceptionsRequest and view policy exceptions
counterparties:readView counterparty information and trust
counterparties:writeCreate and update counterparties
alerts:readView agent alerts
alerts:writeAcknowledge and resolve alerts
agents:readView agent profile and summary
analytics:readView spending analytics and trends
network:readQuery network trust scores
audit:readView audit logs
SDK keys cannot:
  • Create or modify agents
  • Create or modify wallets
  • Change policies
  • Access other agents’ data

​
Key Expiration

Keys can be set to expire:
  • No expiration - Key never expires (default)
  • 30 days - For short-term testing
  • 90 days - For production rotation
  • 365 days - For long-term use
curl -X POST https://conto.finance/api/agents/{agentId}/sdk-keys \
  -H "Authorization: Bearer $CONTO_API_KEY" \
  -d '{
    "name": "Short-term key",
    "expiresInDays": 30
  }'

​
Revoking Keys

​
Via Dashboard

  1. Go to Agents → Your Agent → SDK Keys
  2. Click the Revoke button next to the key

​
Via API

curl -X DELETE "https://conto.finance/api/agents/{agentId}/sdk-keys?keyId={keyId}" \
  -H "Authorization: Bearer $CONTO_API_KEY"
Revoked keys are immediately invalidated and cannot be used.

​
Best Practices

Always use environment variables:
// Bad
const conto = new Conto({
  apiKey: 'conto_agent_abc123...'
});

// Good
const conto = new Conto({
  apiKey: process.env.CONTO_API_KEY!
});
Use different keys for different environments:
.env.development
CONTO_API_KEY=conto_agent_dev_key...
.env.production
CONTO_API_KEY=conto_agent_prod_key...
Set up a key rotation schedule:
  • Generate new key
  • Update environment variables
  • Deploy with new key
  • Revoke old key
Consider using key expiration to enforce rotation.
Check the dashboard for:
  • Usage count
  • Last used timestamp
  • Any authentication errors
For production, use a secrets manager:
  • AWS Secrets Manager
  • HashiCorp Vault
  • Google Secret Manager
  • Azure Key Vault

​
Authentication Errors

Error CodeDescriptionSolution
AUTH_FAILEDInvalid API keyCheck key is correct and not revoked
EXPIRED_KEYKey has expiredGenerate a new key
AGENT_INACTIVEAgent is not activeActivate the agent in dashboard
INSUFFICIENT_SCOPEKey lacks permissionUse a key with required scope
try {
  await conto.payments.pay({ ... });
} catch (error) {
  if (error.code === 'AUTH_FAILED') {
    console.error('Check your API key');
  }
}

​
Next Steps

Payments

Make payments with the SDK

Error Handling

Handle authentication errors