Keys and scopes

Conto SDK requests authenticate with agent-specific SDK keys:

conto_agent_[64-character-hex-string]

Every SDK key belongs to exactly one agent and always expires: the default lifetime is 365 days and the maximum is 730 days.

Choose the right credential

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_...`	Agents that also manage agents, wallets, or policies	Still an agent key. Not accepted by `ContoAdmin`
Organization API key	`conto_...`	Backend/admin automation across the whole organization	Use with `ContoAdmin`

ContoAdmin requires an organization API key from Settings > API Keys. Admin SDK keys can call elevated HTTP API endpoints, but ContoAdmin rejects them.

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 manages agents, wallets, or policies. Only organization owners and admins can create admin keys.

Set expiration

Choose 30, 90, or 180 days, 1 year (the default), or 2 years (the maximum).

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."
}

To create an admin key with "keyType": "admin", the organization API key needs the admin or team:write scope.

Scopes

A scope authorizes an operation. Wallet links, policies, spend limits, approvals, and resource ownership still decide what a key can pay.

Agent key presets

Standard is the default. x402 and MPP recording require payments:execute, not transactions:write, so they work with a standard key.

Scope	Standard	Admin	Operation
`payments:request`	Yes	Yes	Request authorization and protocol pre-authorization
`payments:execute`	Yes	Yes	Execute approved managed payments and record x402/MPP settlement
`payments:approve`	Yes	Yes	Authorize an external-wallet payment
`payments:confirm`	Yes	Yes	Confirm an externally executed payment
`wallets:read`	Yes	Yes	Read wallets, spending limits, and budget requests
`policies:read`	Yes	Yes	Read assigned policies
`transactions:read`	Yes	Yes	Read transactions and payment status
`counterparties:read`	Yes	Yes	Read counterparty relationships
`alerts:read`	Yes	Yes	Read alerts
`agents:read`	Yes	Yes	Read the agent and setup summary
`analytics:read`	Yes	Yes	Read analytics and protocol budget/service summaries
`network:read`	Yes	Yes	Read network trust
`audit:read`	No	Yes	Read audit logs
`alerts:write`	No	Yes	Respond to alerts
`transactions:write`	No	Yes	Retry a definitive failed transfer (also requires `payments:execute`)
`counterparties:write`	No	Yes	Create and update counterparties
`merchant:purchase`	No	Yes	Let Conto complete a card checkout for one approved cart (off unless enabled for the organization)
`policies:exceptions`	No	Yes	Request policy changes for review
`agents:write`	No	Yes	Create and update agents in the organization
`wallets:write`	No	Yes	Create and update wallets in the organization
`policies:write`	No	Yes	Create and update policies in the organization

Admin SDK keys

Admin keys add the scopes that Standard lacks: audit reads, write access to agents, wallets, policies, counterparties, and alerts, retries of failed transfers, policy change requests, and merchant:purchase (off unless Conto enables it for your organization). On organization endpoints an admin key acts with Manager permissions for the whole organization. Admin keys do not include team management, organization settings, or the organization admin super-scope, and an admin key cannot create another admin SDK key.

Organization API key scopes

Only Owners create organization API keys, in Settings > API Keys or with POST /api/api-keys. Organization keys always expire: expiresInDays defaults to 365, which is also the maximum. The dashboard offers three presets, and the API also accepts individual scopes.

Preset	Scopes included
Read Only	`*:read` scopes only
Standard	Read and write for agents, wallets, policies, transactions, counterparties, and alerts, plus analytics, audit, and team read
Admin	All scopes (Owner-only)

Available scopes: agents, wallets, transactions, policies, counterparties, and alerts (each :read and :write), plus analytics:read, audit:read, team:read, team:write, org:read, org:write, and admin.

Revoke keys

Via dashboard

Go to Agents
Open the agent
Open the SDK Integration tab
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 needs elevated management access.
Standard keys can move funds. Limit what they can spend with policies, spend limits, and approvals.
Rotate keys on a schedule instead of waiting for emergency revocations.

Get started

Integrate

Payments

Conto Commerce

Spending controls

Operate

Conto Pay

Keys and scopes

Choose the right credential

Generate SDK keys

Via dashboard

Via API

Scopes

Agent key presets

Admin SDK keys

Organization API key scopes

Revoke keys

Via dashboard

Via API

Best practices

​Choose the right credential

​Generate SDK keys

​Via dashboard

​Via API

​Scopes

​Agent key presets

​Admin SDK keys

​Organization API key scopes

​Revoke keys

​Via dashboard

​Via API

​Best practices

Choose the right credential

Generate SDK keys

Via dashboard

Via API

Scopes

Agent key presets

Admin SDK keys

Organization API key scopes

Revoke keys

Via dashboard

Via API

Best practices