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

# Authentication Tools

> User signup and session management

## Overview

Authentication tools handle user signup via OAuth 2.1 and session status checking.

<Warning>
  **Do NOT use these tools on connector hosts.** Claude.ai, ChatGPT, and other platforms with a built-in MCP connector UI handle authentication through their own connector OAuth flow — Arlo does not advertise `init_signup` or `check_account_status` there, and calling them would create a parallel auth session the connector cannot see. These tools are for agent runtimes that manage their own OAuth (Claude Code, OpenClaw, custom agents).
</Warning>

## init\_signup

Initialize the signup flow for a new Arlo Health user from a non-connector agent.

### Parameters

| Parameter                | Type   | Required | Description                                                         |
| ------------------------ | ------ | -------- | ------------------------------------------------------------------- |
| `baseUrl`                | string | No       | The base URL for the MCP server (e.g., `https://mcp.arlohealth.ai`) |
| `webhookUrl`             | string | No       | URL where Arlo will POST real-time notifications                    |
| `webhookToken`           | string | No       | Bearer token for webhook request verification                       |
| `deliveryContext`        | object | No       | Platform-specific delivery context for webhooks                     |
| `conversationSessionKey` | string | No       | Your platform's session key for threading notifications             |

### Returns

```json theme={null}
{
  "authUrl": "https://auth.arlohealth.ai/authorize?...",
  "sessionId": "sess_abc123...",
  "expiresIn": 900
}
```

| Field       | Description                                  |
| ----------- | -------------------------------------------- |
| `authUrl`   | URL for user to click and complete signup    |
| `sessionId` | Session identifier for polling status        |
| `expiresIn` | Seconds until auth link expires (15 minutes) |

### Example

```json theme={null}
{
  "webhookUrl": "https://your-agent.com/hooks/arlo",
  "webhookToken": "secret-token-123",
  "deliveryContext": {
    "to": "+15551234567",
    "channel": "whatsapp",
    "deliver": true
  },
  "conversationSessionKey": "conv_xyz789"
}
```

### Webhook Setup

<Note>
  Pass webhook configuration during `init_signup` to receive real-time push notifications. You can also register or update webhooks after authentication using `register_webhook`. If `init_signup` is called **without** `webhookUrl`, any existing webhook configuration is preserved.
</Note>

See [Webhooks](/mcp-tools/webhooks) for full webhook documentation.

***

## check\_account\_status

Check authentication and webhook status for an Arlo session.

### Parameters

| Parameter   | Type   | Required | Description                                          |
| ----------- | ------ | -------- | ---------------------------------------------------- |
| `sessionId` | string | No       | Session ID from `init_signup` to poll for completion |

### Behavior

**With `sessionId`:** Polls for auth completion. Returns `authenticated: false` while pending, `authenticated: true` once complete.

**Without `sessionId`:** Returns webhook status for all configured sessions and general authentication status.

### Returns

```json theme={null}
{
  "authenticated": true,
  "status": "complete",
  "userName": "John Doe",
  "linkedAt": "2026-01-15T10:30:00Z",
  "sessionId": "sess_abc123",
  "webhookConfigured": true,
  "webhookUrl": "https://your-agent.com/hooks/arlo"
}
```

| Field               | Description                           |
| ------------------- | ------------------------------------- |
| `authenticated`     | Whether the user is authenticated     |
| `status`            | `pending` or `complete`               |
| `userName`          | User's name (when authenticated)      |
| `linkedAt`          | Timestamp when auth completed         |
| `sessionId`         | The session identifier                |
| `webhookConfigured` | Whether push notifications are set up |
| `webhookUrl`        | Configured webhook URL (if any)       |

<Note>
  `check_account_status` also reports webhook configuration, so it doubles as the webhook status check on the MCP surface.
</Note>

### Polling Pattern

```javascript theme={null}
async function waitForAuth(sessionId) {
  while (true) {
    const status = await checkAccountStatus({ sessionId });
    if (status.authenticated) {
      return status;
    }
    await sleep(2000); // Poll every 2 seconds
  }
}
```

<Tip>
  Poll every 2-3 seconds while waiting for authentication to complete. The auth link expires after 15 minutes.
</Tip>