Skip to main content

​
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_...The agent payment lifecycle (request, execute, approve, confirm) plus agent-scoped readsWorks 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 the payment lifecycle plus read access, or Admin if the agent also 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": "cmm5d0key000l49h7entvd11p",
  "key": "conto_agent_abc123def456...",
  "name": "Production Key",
  "keyType": "standard",
  "scopes": [
    "payments:request",
    "payments:execute",
    "payments:approve",
    "payments:confirm",
    "wallets:read",
    "policies:read",
    "transactions:read",
    "counterparties:read",
    "alerts:read",
    "agents:read",
    "analytics:read",
    "network:read"
  ],
  "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 the standard preset shown above: the payment lifecycle plus read scopes.

​
Use SDK Keys

Client initialization and environment-variable setup live in SDK Installation: pass the agent SDK key as apiKey to Conto, and the organization API key as orgApiKey to ContoAdmin.

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, and delete wallet operations through the Admin SDK or the corresponding /api/wallets HTTP endpoints. To archive a wallet, use update({ status: 'ARCHIVED' }).

​
Standard SDK Scopes

Standard SDK keys cover the full payment lifecycle plus read access. Spending control comes from policies, spend limits, approvals, and custody, not from withholding payment scopes.
ScopeIncluded by defaultDescription
payments:requestYesRequest policy evaluation for a payment
payments:executeYesExecute approved payments or use autoExecute
payments:approveYesApprove external-wallet payments
payments:confirmYesConfirm external-wallet payments
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
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 preset, and the creation response lists the granted scopes. Every payment a standard key executes still passes through policy evaluation, spend limits, and any approval workflows. Use keyType: "admin" only when the agent 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.
  • Standard keys can move funds, so constrain agents with policies, spend limits, and approval workflows rather than treating the key as the control surface.
  • Rotate keys on a schedule instead of waiting for emergency revocations.