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_...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",
    "scopes": ["payments:request", "payments:execute", "wallets:read"]
  }'
Response 
{
  "id": "key_abc123",
  "key": "conto_agent_abc123def456...",
  "keyPrefix": "conto_agent_abc...",
  "name": "Production Key",
  "keyType": "standard",
  "expiresAt": "2026-07-15T10:00:00Z",
  "message": "Save this key now! It will not be shown again."
}

​
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.

​
Standard SDK Scopes

If you omit scopes, standard SDK keys get 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
Use the scopes array when creating a standard SDK key via API if the agent needs more than the default preset.

​
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.