Authentication

​

Overview

​

Discovery endpoints

​

OAuth authorization server metadata

{
  "issuer": "https://mcp.arlohealth.ai",
  "authorization_endpoint": "https://mcp.arlohealth.ai/oauth/authorize",
  "token_endpoint": "https://mcp.arlohealth.ai/oauth/token",
  "registration_endpoint": "https://mcp.arlohealth.ai/register",
  "service_documentation": "https://mcp.arlohealth.ai/AGENTS.md",
  "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"]
}

​

The OAuth flow

​

Checklist for a self-hosted MCP client

1. Read the metadata first. Use the authorization_endpoint and token_endpoint it returns. Don’t hardcode paths. (As a fallback for SDKs that skip discovery, /authorize and /token at the root behave identically to /oauth/authorize and /oauth/token.)
2. Dynamic client registration is supported at /register (RFC 7591). No pre-registration is needed. PKCE with S256 is required, and the client is public (token_endpoint_auth_method: none).
3. Your redirect_uri must be an endpoint your client is listening on when the user’s browser is redirected back. This is the most common self-hosted failure:
   • Cloud or remote agents: use a publicly reachable HTTPS callback. Never localhost. A localhost callback points at the user’s device, where your agent isn’t running, so the sign-in result can never reach you.
   • Local clients (CLI agents, MCP Inspector): a loopback http://localhost:<port>/... callback is fine, but the listener must be running for the whole flow.
   • Malformed or insecure values are rejected at /oauth/authorize with a 400 JSON error (error, error_description, hint). Unreachable loopback callbacks show the user a guided error page instead of failing silently.
4. The flow needs a browser. Authorization is interactive. A headless client must open the authorization URL in a real browser rather than expecting a device-code flow.
5. After connecting, reload the tool list. Some clients cache the tool list from before auth completed.

​

Session-based signup (init_signup)

{
  "webhookUrl": "https://your-agent/hooks/arlo",
  "webhookToken": "secret-token"
}

{
  "authUrl": "https://mcp.arlohealth.ai/c/abc123",
  "sessionId": "sess_abc123",
  "expiresIn": 900,
  "instructions": "Show authUrl to the user. It is single-use and expires in 15 minutes. Poll check_account_status with sessionId."
}

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);
  }
  throw new Error("Authentication timed out");
}

​

Scopes

​

Tokens

• Send the access token as Authorization: Bearer <token> on every MCP and REST request. MCP clients manage this for you.
• Access tokens are long-lived for connector hosts, so a connector stays connected without refreshing. Refresh when you receive a 401.
• Refresh tokens rotate. Every refresh returns a new refresh token; store it and discard the old one. Parallel refreshes of the same token are served the same new pair, so a race does not log the user out.
• A 503 temporarily_unavailable with a Retry-After header from the token endpoint, or from the MCP transport, means the auth backend is briefly unreachable. It is not an authentication failure: keep your tokens and retry after the delay. Only a 401 or an invalid_grant means the user must sign in again.

​

Webhook registration

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

​

Session management

• Sessions are tied to the user’s Arlo account and persist until revoked.
• Webhook registrations persist per session.
• If a session expires or the user revokes access: run the OAuth flow again (or init_signup), then re-register the webhook if needed.
• check_account_status without a sessionId reports the current session and all webhook configurations:

{
  "authenticated": true,
  "webhookConfigured": true,
  "sessions": [
    {
      "sessionKey": "sess_abc123",
      "webhookUrl": "https://your-agent/hooks/arlo",
      "configured": true,
      "hasSecret": true,
      "hasDeliveryContext": true,
      "failureCount": 0,
      "updatedAt": "2026-08-15T10:30:00Z"
    }
  ]
}

​

Security best practices

​

Webhook token security

• Use cryptographically random tokens
• Store tokens securely (environment variables, a secrets manager)
• Rotate tokens periodically, by calling register_webhook with the new one
• Always validate tokens on incoming webhooks

​

PKCE requirements

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

​

Errors