Authentication

Overview

Arlo Health uses OAuth 2.1 with PKCE (Proof Key for Code Exchange) for authentication. This provides secure authentication without requiring the agent to handle user credentials.

On connector hosts (Claude.ai, ChatGPT) the platform’s connector UI runs this whole flow for you — init_signup and check_account_status are not advertised there and must not be called. The flow below is for agent runtimes that manage their own OAuth (Claude Code, OpenClaw, custom agents).

OAuth 2.1 Flow

Discovery Endpoints

Arlo exposes standard OAuth 2.1 discovery endpoints:

Endpoint	Purpose
`/.well-known/mcp.json`	MCP Server Card with capabilities and auth info
`/.well-known/oauth-protected-resource`	RFC 9728 protected resource metadata
`/.well-known/oauth-authorization-server`	OAuth authorization server metadata

MCP Server Card

{
  "name": "arlo-health",
  "version": "1.0.0",
  "description": "Healthcare infrastructure for AI agents",
  "publisher": {
    "name": "Arlo Health",
    "url": "https://www.arlohealth.ai"
  },
  "transport": {
    "type": "streamable-http",
    "url": "https://mcp.arlohealth.ai/mcp"
  },
  "authentication": {
    "type": "oauth2",
    "metadata_url": "https://mcp.arlohealth.ai/.well-known/oauth-authorization-server"
  }
}

OAuth Authorization Server Metadata

{
  "issuer": "https://mcp.arlohealth.ai",
  "authorization_endpoint": "https://auth.arlohealth.ai/authorize",
  "token_endpoint": "https://mcp.arlohealth.ai/oauth/token",
  "registration_endpoint": "https://mcp.arlohealth.ai/oauth/register",
  "response_types_supported": ["code"],
  "grant_types_supported": ["authorization_code", "refresh_token"],
  "code_challenge_methods_supported": ["S256"],
  "token_endpoint_auth_methods_supported": ["none"],
  "scopes_supported": ["openid", "profile", "email", "offline_access"]
}

Authentication Flow

Call init_signup to begin the OAuth flow:

{
  "baseUrl": "https://mcp.arlohealth.ai",
  "webhookUrl": "https://your-agent/hooks/arlo",
  "webhookToken": "secret-token"
}

Response:

{
  "authUrl": "https://auth.arlohealth.ai/authorize?...",
  "sessionId": "sess_abc123",
  "expiresIn": 900
}

Step 2: User Completes Auth

Direct the user to open authUrl in their browser. They will:

Create an account or sign in
Grant permissions to your agent
Be redirected back to Arlo

Step 3: Poll for Completion

Poll check_account_status until authentication completes:

async function waitForAuth(sessionId) {
  const maxAttempts = 90; // 15 minutes at 10s intervals

  for (let i = 0; i < maxAttempts; i++) {
    const status = await checkAccountStatus({ sessionId });

    if (status.authenticated) {
      return status;
    }

    await sleep(10000); // 10 seconds
  }

  throw new Error("Authentication timed out");
}

The auth link expires after 15 minutes. If the user doesn’t complete authentication, you’ll need to call init_signup again.

Scopes

Scope	Description	Required
`openid`	OpenID Connect identifier	Yes
`profile`	User profile information	Yes
`email`	User email address	Yes
`offline_access`	Refresh tokens for long-lived sessions	Recommended

Token Management

Access Tokens

Short-lived (typically 1 hour)
Include in requests as Authorization: Bearer <token>
Automatically managed by MCP clients

Refresh Tokens

Long-lived (days/weeks)
Use to obtain new access tokens
Requires offline_access scope

Token Refresh Flow

Webhook Registration

The best time to register webhooks is during init_signup:

{
  "baseUrl": "https://mcp.arlohealth.ai",
  "webhookUrl": "https://your-agent/hooks/arlo",
  "webhookToken": "your-secret-token",
  "deliveryContext": {
    "to": "+15551234567",
    "channel": "whatsapp",
    "deliver": true
  },
  "conversationSessionKey": "your-session-key"
}

You can also register or update webhooks after authentication using register_webhook. If you call init_signup without webhook parameters, existing webhook config is preserved.

Session Management

Session Persistence

Sessions are tied to the user’s Arlo account
Sessions persist until explicitly revoked
Webhook registrations are permanent per session

Re-authentication

If a session expires:

Call init_signup again
User completes OAuth flow
New session is created
Re-register webhooks if needed

Checking Session Status

Use check_account_status without a sessionId to check the current session:

{
  "authenticated": true,
  "webhookConfigured": true,
  "sessions": [
    {
      "sessionId": "sess_abc123",
      "linkedAt": "2024-01-15T10:30:00Z",
      "webhookUrl": "https://your-agent/hooks/arlo"
    }
  ]
}

Security Best Practices

Webhook Token Security

Use cryptographically random tokens
Store tokens securely (environment variables, secrets manager)
Rotate tokens periodically
Always validate tokens on incoming webhooks

PKCE Requirements

Always use S256 code challenge method
Generate cryptographically random code verifiers
Never reuse code verifiers

Error Handling

Common Authentication Errors

Error	Cause	Resolution
`not_authenticated`	No valid session	Call `init_signup`
`token_expired`	Access token expired	Refresh token
`invalid_grant`	Refresh token invalid	Re-authenticate
`session_revoked`	User revoked access	Re-authenticate

Getting Started

Tutorials

Concepts

Overview

OAuth 2.1 Flow

Discovery Endpoints

MCP Server Card

OAuth Authorization Server Metadata

Authentication Flow

Step 2: User Completes Auth

Step 3: Poll for Completion

Scopes

Token Management

Access Tokens

Refresh Tokens

Token Refresh Flow

Webhook Registration

Session Management

Session Persistence

Re-authentication

Checking Session Status

Security Best Practices

Webhook Token Security

PKCE Requirements

Error Handling

Common Authentication Errors

​Overview

​OAuth 2.1 Flow

​Discovery Endpoints

​MCP Server Card

​OAuth Authorization Server Metadata

​Authentication Flow

​Step 1: Initialize Signup

​Step 2: User Completes Auth

​Step 3: Poll for Completion

​Scopes

​Token Management

​Access Tokens

​Refresh Tokens

​Token Refresh Flow

​Webhook Registration

​Session Management

​Session Persistence

​Re-authentication

​Checking Session Status

​Security Best Practices

​Webhook Token Security

​PKCE Requirements

​Error Handling

​Common Authentication Errors

Overview

OAuth 2.1 Flow

Discovery Endpoints

MCP Server Card

OAuth Authorization Server Metadata

Authentication Flow

Step 1: Initialize Signup

Step 2: User Completes Auth

Step 3: Poll for Completion

Scopes

Token Management

Access Tokens

Refresh Tokens

Token Refresh Flow

Webhook Registration

Session Management

Session Persistence

Re-authentication

Checking Session Status

Security Best Practices

Webhook Token Security

PKCE Requirements

Error Handling

Common Authentication Errors