# Scoped SMS and TOTP for agents

An agent connection can use the phone numbers and TOTP devices allowed by its permissions and resource scope. The operator provisions and assigns resources; the running agent discovers what it can access with `agentGetCapabilities` and the channel-specific listing operations.

## Assign phone numbers before the agent runs

Provision numbers through the dashboard or account API and assign the intended numbers to the agent connection. A scoped agent's phone listing returns only active assigned numbers. Phone provisioning is an operator action, separate from an agent reading or replying to SMS.

[API endpoint: `agentGetPhoneNumbers`](/docs/api/#agentGetPhoneNumbers)

[API endpoint: `agentGetReceivedSmsMessages`](/docs/api/#agentGetReceivedSmsMessages)

Keep SMS read/history permissions separate from SMS send permission. Replying requires both because the agent reads an inbound message before sending its response. An email role or inbox assignment alone should not be assumed to grant phone access; check capabilities and the assigned resources.

## Read and reply within scope

1. List the assigned phones and select the intended phone ID.
2. List its received SMS or message threads, using a time boundary when following a new action.
3. Retrieve the selected message and verify that it belongs to the intended workflow.
4. Reply only when the connection has the required permission and the application authorizes the response.
5. Inspect sent history and activity to confirm the outcome.

[API endpoint: `agentGetPhoneMessageThreads`](/docs/api/#agentGetPhoneMessageThreads)

[API endpoint: `agentReplyToSms`](/docs/api/#agentReplyToSms)

[API endpoint: `agentSendSms`](/docs/api/#agentSendSms)

For supervised SMS conversations, use the SMS claim, renewal and handoff operations. Do not reuse email conversation IDs or assume an email claim also reserves a phone.

[API endpoint: `agentClaimSmsConversation`](/docs/api/#agentClaimSmsConversation)

[API endpoint: `agentRenewSmsClaim`](/docs/api/#agentRenewSmsClaim)

[API endpoint: `agentRequestSmsHandoff`](/docs/api/#agentRequestSmsHandoff)

## Use an authenticator device

For applications using TOTP, list or find an agent-accessible device, then generate a code for the authorized authentication step. With the appropriate permissions, agent-managed devices can be created from a base32 secret or an `otpauth` URL.

[API endpoint: `agentGetTotpDevices`](/docs/api/#agentGetTotpDevices)

[API endpoint: `agentCreateTotpDeviceForOtpAuthUrl`](/docs/api/#agentCreateTotpDeviceForOtpAuthUrl)

[API endpoint: `agentGenerateTotpDeviceCode`](/docs/api/#agentGenerateTotpDeviceCode)

Treat the enrollment secret and generated code as credentials. Keep them out of shared logs, generate a fresh code near the submission step and verify the application's authenticated state. See [TOTP testing](/docs/totp/) for the enrollment and verification flow.

## Choose the correct credential

Use a scoped agent key for the operations documented here. An account key belongs in a separate provisioning service when account-level setup is required. For browser-test suites using ordinary account APIs, see [SMS waits](/docs/wait-for/#wait-for-sms) and [phone pool leases](/docs/phone-pools/). Check the connected MCP client's available tool list before assuming every REST operation is exposed as an MCP tool.