> ## Documentation Index
> Fetch the complete documentation index at: https://conto.finance/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> Generate and manage SDK keys for agent authentication, choose the right credential type, and set up key rotation

# SDK Authentication

Conto SDK requests authenticate with agent-specific SDK keys:

```text theme={null}
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.
</Info>

## Generate SDK Keys

### Via Dashboard

<Steps>
  <Step title="Open the agent">Go to **Agents** and select the agent that will use the key.</Step>
  <Step title="Create a key">Open **SDK Keys** and click **Generate New Key**.</Step>

  <Step title="Choose a preset">
    Select **Standard** for the payment lifecycle plus read access, or **Admin** if the agent also
    needs elevated management access.
  </Step>

  <Step title="Set expiration">
    Choose an expiration window. Keys default to 365 days and cannot exceed 730 days.
  </Step>

  <Step title="Copy the secret">
    <Warning>
      The full key is shown only once. Store it in your secrets manager before closing the dialog.
    </Warning>
  </Step>
</Steps>

### Via API

```bash theme={null}
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 theme={null}
{
  "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.
</Info>

## Use SDK Keys

Client initialization and environment-variable setup live in
[SDK Installation](/sdk/installation): pass the agent SDK key as `apiKey` to `Conto`, and the
organization API key as `orgApiKey` to `ContoAdmin`.

<Card title="Admin SDK Reference" icon="shield" href="/sdk/admin">
  Use organization API keys with `ContoAdmin` for organization-wide provisioning and management.
</Card>

<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' })`.
</Info>

## 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                                           |

<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.
</Info>

## 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               |

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

## Revoke Keys

### Via Dashboard

1. Go to **Agents**
2. Open the agent
3. Open **SDK Keys**
4. Click **Revoke**

### Via API

```bash theme={null}
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.