Machine View
Authentication
Source: https://conto.finance/docs/sdk/authentication
# Authentication
> Generate and manage SDK keys for agent authentication, choose the right credential type, and set up key rotation
- Human URL: https://conto.finance/docs/sdk/authentication
- Raw Markdown: https://conto.finance/docs/sdk/authentication.md
- Terminal view: https://conto.finance/ai/docs/sdk/authentication
Documentation group: Build
# SDK Authentication
Conto SDK requests authenticate with agent-specific SDK keys:
```text
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` |
Info:
`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
Go to **Agents** and select the agent that will use the key.
Open the **SDK Integration** tab and click **Generate SDK Key**.
Select **Standard** for the payment lifecycle plus read access, or **Admin** if the agent also
needs elevated management access.
Choose an expiration window. Keys default to 365 days and cannot exceed 730 days.
The full key is shown only once. Store it in your secrets manager before closing the dialog.
### Via API
```bash
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**
```json
{
"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."
}
```
Info:
`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](https://conto.finance/sdk/installation): pass the agent SDK key as `apiKey` to `Conto`, and the
organization API key as `orgApiKey` to `ContoAdmin`.
### Admin SDK Reference
Link: https://conto.finance/sdk/admin
Use organization API keys with `ContoAdmin` for organization-wide provisioning and management.
Info:
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 |
| `counterparties:write` | No | Create and update counterparties |
| `alerts:write` | No | Acknowledge and resolve alerts |
| `audit:read` | No | View audit logs |
| `policies:exceptions` | No | Request and track a scoped policy change |
Info:
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`
- `policies:exceptions`
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
1. Go to **Agents**
2. Open the agent
3. Open **SDK Keys**
4. Click **Revoke**
### Via API
```bash
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.