Admin SDK

# Admin SDK

> Manage Conto agents, wallets, policies, and SDK keys with organization API keys.

- Human URL: https://conto.finance/docs/sdk/admin
- Raw Markdown: https://conto.finance/docs/sdk/admin.md
- Terminal view: https://conto.finance/ai/docs/sdk/admin

Documentation group: Build

# Admin SDK

Use `ContoAdmin` for organization-level automation: provisioning agents, attaching wallets, assigning
policies, and creating agent SDK keys. Use the regular `Conto` client for agent runtime payment
calls.

| Client       | Credential                        | Use for                                         |
| ------------ | --------------------------------- | ----------------------------------------------- |
| `ContoAdmin` | Organization API key, `conto_...` | Agents, wallets, policies, SDK key lifecycle    |
| `Conto`      | Agent SDK key, `conto_agent_...`  | Payment requests, execution, agent-scoped reads |

## Initialize

```typescript

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

Create organization API keys from **Settings > API Keys**. Store them in a secret manager and use
the smallest scope preset that can perform the job.

## Provision an agent

This is the common backend setup flow:

```typescript

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

const { members } = await admin.team.listMembers();
const owner = members.find((member) => member.user?.email === 'ops@example.com');

const wallet = await admin.wallets.create({
  name: 'ops-wallet',
  chainType: 'EVM',
  custodyMode: 'MANAGED',
  controlModel: 'ORGANIZATION_CONTROLLED',
});
await admin.wallets.provision(wallet.id);

const policy = await admin.policies.create({
  name: 'Daily $500 limit',
  policyType: 'SPEND_LIMIT',
  rules: [{ ruleType: 'DAILY_LIMIT', operator: 'LTE', value: '500' }],
});

const agent = await admin.agents.create({
  name: 'ops-agent',
  agentType: 'CUSTOM',
  externalId: 'erp-agent-42',
  ownerMembershipId: owner?.id,
  allowedContexts: ['supplier-payments'],
  callbackUrl: 'https://agent.example.com/webhooks/conto',
});

await admin.agents.linkWallet(agent.id, {
  walletId: wallet.id,
  delegationType: 'LIMITED',
  spendLimitPerTx: 100,
  spendLimitDaily: 500,
});

await admin.agents.assignPolicy(agent.id, policy.id);

const { key } = await admin.agents.createSdkKey(agent.id, {
  name: 'Production',
  keyType: 'standard',
  expiresInDays: 90,
});
```

The returned SDK key is shown once. Pass it to the agent runtime as `CONTO_API_KEY`.

`ORGANIZATION_CONTROLLED` requires the organization owner to register its public authorization key
in **Settings → Wallet Control** first. Use `CONTO_MANAGED` when customer self-service key export is
not required. Wallet responses return `controlModel` and `keyAccess` so provisioning systems can
reconcile the selected boundary without receiving provider IDs. Organization-controlled creation
is currently EVM-only until a validated Solana provider policy is configured. If `keyAccess` is
`EXPORT_RECONCILIATION_REQUIRED`, fail closed and wait for provider reconciliation before attempting
another export.

Agent responses include the caller-owned `externalId`, parsed `allowedContexts`, the owner's stable
membership reference, and callback configuration so provisioning systems can reconcile what Conto
stored. Callback query and fragment values are redacted in responses; send `callbackUrl` again when
rotating a callback token. `agents.list({ search })` also matches `externalId`.

The `setup` field reports `READY` or `ACTION_REQUIRED` with normalized issues and the request field
to update. It is intended for customer setup automation; provider state and arbitrary agent metadata
are not returned. `linkedWalletCount` and `transactionCount` provide stable list-level reconciliation
counts without exposing database relation objects.

## Method map

| Area               | Methods                                                                                  |
| ------------------ | ---------------------------------------------------------------------------------------- |
| Agents             | `agents.list`, `agents.create`, `agents.get`, `agents.update`, `agents.delete`           |
| Agent state        | `agents.freeze`, `agents.unfreeze`                                                       |
| Agent links        | `agents.linkWallet`, `agents.listWallets`, `agents.assignPolicy`, `agents.listPolicies`  |
| SDK keys           | `agents.createSdkKey`, `agents.listSdkKeys`, `agents.revokeSdkKey`                       |
| Team               | `team.listMembers`                                                                       |
| Wallets            | `wallets.list`, `wallets.create`, `wallets.get`, `wallets.update`, `wallets.delete`      |
| Wallet chain state | `wallets.provision`, `wallets.refreshBalance`                                            |
| Policies           | `policies.list`, `policies.create`, `policies.get`, `policies.update`, `policies.delete` |
| Policy rules       | `policies.addRule`, `policies.addRules`, `policies.updateRule`, `policies.deleteRule`    |
| Policy versions    | `policies.listVersions`, `policies.getVersion`, `policies.compareVersions`, `policies.rollbackVersion` |

## Policy version history

Every change to a policy is versioned. Review the history, diff two versions, and roll back.

```typescript
const { versions } = await admin.policies.listVersions(policy.id);
const latest = versions[0].version;

// See what changed between two versions.
const { diff } = await admin.policies.compareVersions(policy.id, latest - 1, latest);

// Restore an earlier version. If your organization requires governance approval
// for policy changes, the response indicates the rollback is pending approval
// instead of applying it.
const result = await admin.policies.rollbackVersion(policy.id, latest - 1, {
  note: 'revert the vendor cap change',
});
```

## Scopes

Admin SDK methods use organization API key scopes. Read methods need the matching `*:read` scope.
Create, update, delete, link, assign, provision, freeze, and revoke methods need the matching
`*:write` or admin scope. See [Authentication](https://conto.finance/sdk/authentication#admin-sdk-keys) for key creation
and rotation.

## Security notes

- Organization keys can manage all agents and wallets in the organization.
- Prefer scoped keys for CI and provisioning jobs.
- Rotate keys regularly and revoke unused keys.
- Billing plan changes are available only to owners in the dashboard; organization API keys cannot
  change billing plans.

## Related

### Authentication
Link: https://conto.finance/sdk/authentication

    Key types, scopes, and rotation

### Payments
Link: https://conto.finance/sdk/payments

    Agent runtime payment calls

### Policies
Link: https://conto.finance/policies/overview

    Policy types and evaluation behavior

### API Reference
Link: https://conto.finance/api/reference

    OpenAPI and REST reference links