Skip to main content

Documentation Index

Fetch the complete documentation index at: https://conto.finance/docs/llms.txt

Use this file to discover all available pages before exploring further.

​
SDK Authentication

Conto SDK requests authenticate with agent-specific SDK keys: 
conto_agent_[64-character-hex-string]
Every SDK key belongs to exactly one agent. SDK keys always expire automatically: the default lifetime is 365 days and the maximum is 730 days.

​
Choose the Right Credential

Use the credential type that matches the job you need to do:
CredentialFormatBest forNotes
Standard SDK keyconto_agent_...Agent payment requests and agent-scoped read accessWorks with the Conto client
Admin SDK keyconto_agent_...Delegated agent workflows that need elevated access to agents, wallets, or policiesAgent-scoped identity with an expanded scope preset
Organization API keyconto_...Backend/admin automation across the whole organizationUse with ContoAdmin
ContoAdmin requires an organization API key. Admin SDK keys can call elevated HTTP API endpoints, but they are not a drop-in replacement for the ContoAdmin constructor.

​
Generate SDK Keys

​
Via Dashboard

1

Open the agent

Go to Agents and select the agent that will use the key.
2

Create a key

Open SDK Keys and click Generate New Key.
3

Choose a preset

Select Standard for least-privilege access or Admin if the agent needs elevated management access.
4

Set expiration

Choose an expiration window. Keys default to 365 days and cannot exceed 730 days.
5

Copy the secret

The full key is shown only once. Store it in your secrets manager before closing the dialog.

​
Via API

curl -X POST https://conto.finance/api/agents/{agentId}/sdk-keys \
  -H "Authorization: Bearer $CONTO_ORG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production Key",
    "expiresInDays": 90,
    "keyType": "standard"
  }'
Response 
{
  "id": "key_abc123",
  "key": "conto_agent_abc123def456...",
  "name": "Production Key",
  "keyType": "standard",
  "message": "Save this key now! It will not be shown again."
}
POST /api/agents/{agentId}/sdk-keys accepts name, optional expiresInDays, and optional keyType. Standard keys created through this endpoint use Conto’s default least-privilege SDK preset.

​
Use SDK Keys

​
Initialize the agent SDK

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

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

​
Use environment variables

.env
CONTO_API_KEY=conto_agent_abc123def456...

​
Use org keys with ContoAdmin

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

const admin = new ContoAdmin({
  orgApiKey: process.env.CONTO_ORG_API_KEY!,
});

Admin SDK Reference

Use organization API keys with ContoAdmin for organization-wide provisioning and management.
Organization API keys are the right credential for programmatic wallet provisioning and cleanup. That includes create, get, update, archive, and delete wallet operations through the Admin SDK or the corresponding /api/wallets HTTP endpoints.

​
Standard SDK Scopes

Standard SDK keys use the default least-privilege preset:
ScopeIncluded by defaultDescription
payments:requestYesRequest policy evaluation for a payment
wallets:readYesView wallet balances and limits
policies:readYesView policies assigned to the agent
transactions:readYesView transaction history
counterparties:readYesView counterparties and trust data
alerts:readYesView alerts related to the agent
agents:readYesView agent profile and setup summary
analytics:readYesView spend analytics
network:readYesQuery network trust data
payments:executeNoExecute approved payments or use autoExecute
payments:approveNoApprove external-wallet payments
payments:confirmNoConfirm external-wallet payments
transactions:writeNoRetry failed transactions or record x402/MPP transactions
policies:exceptionsNoRequest and view policy exceptions
counterparties:writeNoCreate and update counterparties
alerts:writeNoAcknowledge and resolve alerts
audit:readNoView audit logs
Standard SDK keys created through the SDK-key management endpoint start from this default preset. Use keyType: "admin" only when the agent truly needs delegated management access to agents, wallets, or policies.

​
Admin SDK Keys

Admin SDK keys use an elevated preset intended for delegated agent management workflows. They include:
  • All standard SDK scopes
  • agents:write
  • wallets:write
  • policies:write
They do not include organization-superuser capabilities such as team management, organization settings, or the admin super-scope. They also cannot create other admin SDK keys. That escalation path is blocked intentionally.

​
Key Expiration

All SDK keys have a mandatory expiration.
ValueBehavior
OmittedDefaults to 365 days
30Short-lived testing key
90Recommended production rotation window
365Long-lived standard key
730Maximum allowed lifetime
There is no non-expiring SDK key mode. Build key rotation into your operational runbooks.

​
Revoke Keys

​
Via Dashboard

  1. Go to Agents
  2. Open the agent
  3. Open SDK Keys
  4. Click Revoke

​
Via API

curl -X DELETE "https://conto.finance/api/agents/{agentId}/sdk-keys?keyId={keyId}" \
  -H "Authorization: Bearer $CONTO_ORG_API_KEY"
Revocation is immediate.

​
Best Practices

  • Store SDK keys in a secrets manager, not in source control.
  • Use separate keys for development, staging, and production.
  • Prefer standard keys unless the agent truly needs elevated management access.
  • Grant payments:execute only to agents that should actually move funds.
  • Rotate keys on a schedule instead of waiting for emergency revocations.