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:

Credential	Format	Best for	Notes
Standard SDK key	`conto_agent_...`	The agent payment lifecycle (request, execute, approve, confirm) plus agent-scoped reads	Works with the `Conto` client
Admin SDK key	`conto_agent_...`	Delegated agent workflows that need elevated access to agents, wallets, or policies	Agent-scoped identity with an expanded scope preset
Organization API key	`conto_...`	Backend/admin automation across the whole organization	Use 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

Open the agent

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

Create a key

Open the SDK Integration tab and click Generate SDK Key.

Choose a preset

Select Standard for the payment lifecycle plus read access, or Admin if the agent also needs elevated management access.

Set expiration

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

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.

Scope	Included by default	Description
`payments:request`	Yes	Request policy evaluation for a payment
`payments:execute`	Yes	Execute approved payments or use `autoExecute`
`payments:approve`	Yes	Approve external-wallet payments
`payments:confirm`	Yes	Confirm external-wallet payments
`wallets:read`	Yes	View wallet balances and limits
`policies:read`	Yes	View policies assigned to the agent
`transactions:read`	Yes	View transaction history
`counterparties:read`	Yes	View counterparties and trust data
`alerts:read`	Yes	View alerts related to the agent
`agents:read`	Yes	View agent profile and setup summary
`analytics:read`	Yes	View spend analytics
`network:read`	Yes	Query network trust data
`transactions:write`	No	Retry failed transactions or record x402/MPP transactions
`policies:exceptions`	No	Request and view policy exceptions
`counterparties:write`	No	Create and update counterparties
`alerts:write`	No	Acknowledge and resolve alerts
`audit:read`	No	View 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.

Value	Behavior
Omitted	Defaults to 365 days
`30`	Short-lived testing key
`90`	Recommended production rotation window
`365`	Long-lived standard key
`730`	Maximum allowed lifetime

There is no non-expiring SDK key mode. Build key rotation into your operational runbooks.

Revoke Keys

Via Dashboard

Go to Agents
Open the agent
Open SDK Keys
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.

Start

Products

Build

Guides

Reference

Changelog

Authentication

SDK Authentication

Choose the Right Credential

Generate SDK Keys

Via Dashboard

Via API

Use SDK Keys

Admin SDK Reference

Standard SDK Scopes

Admin SDK Keys

Key Expiration

Revoke Keys

Via Dashboard

Via API

Best Practices

​SDK Authentication

​Choose the Right Credential

​Generate SDK Keys

​Via Dashboard

​Via API

​Use SDK Keys

Admin SDK Reference

​Standard SDK Scopes

​Admin SDK Keys

​Key Expiration

​Revoke Keys

​Via Dashboard

​Via API

​Best Practices

SDK Authentication

Choose the Right Credential

Generate SDK Keys

Via Dashboard

Via API

Use SDK Keys

Standard SDK Scopes

Admin SDK Keys

Key Expiration

Revoke Keys

Via Dashboard

Via API

Best Practices