# Nas.com Agent Authentication

Nas.com public discovery documents are read-only and available without
credentials. The separate hosted Nas.com MCP at `https://mcp.nas.com/mcp`
uses lazy authentication: clients can connect, initialize, discover tools, and
start text-only business onboarding before signing in. Protected business and
payment tools require OAuth.

Use this page as the canonical Nas.com MCP authentication boundary.

## Discover

- MCP endpoint: `https://mcp.nas.com/mcp`
- Protected-resource metadata:
  `https://mcp.nas.com/.well-known/oauth-protected-resource`
- Authorization server: `https://auth.nas.com`
- Authorization-server metadata:
  `https://auth.nas.com/.well-known/oauth-authorization-server`
- Registration proxy: `https://mcp.nas.com/register`
- Authorization proxy: `https://mcp.nas.com/authorize`
- Token proxy: `https://mcp.nas.com/token`
- Revocation proxy: `https://mcp.nas.com/revoke`
- Install guide: `https://nas.com/mcp`
- Agent guide: `https://nas.com/mcp/llms.txt`

## Lazy Authentication

These protocol methods are available without a bearer token:

- `initialize`
- `notifications/initialized`
- `ping`
- `tools/list`

These onboarding calls are also available without authentication:

- `create_image_asset_upload` only with `useCase: "onboarding"`
- `create_onboarded_business`
- `get_onboarding_plan_options`
- `generate_plan_checkout_link`

Anonymous `create_onboarded_business` returns an
`onboardingSessionObjectId` after generating identity and branding. It does
not call the protected draft-business endpoint. An already-authenticated
caller also receives the draft business.

All other tools require authentication. If a protected call returns `401`
with `WWW-Authenticate`, complete OAuth through the advertised metadata and
retry the original tool call. Invalid supplied credentials never downgrade to
anonymous access.

## OAuth Scopes

- `nas.communities.read`
- `nas.communities.write`
- `nas.members.read`
- `nas.products.read`
- `nas.products.write`
- `nas.orders.read`

Request only the scopes needed by the live tool and user request.

## Access and Refresh Tokens

Protected MCP requests send the Nas.com access token in the header:

```http
Authorization: Bearer <nas_access_token>
```

Clients may also send:

```http
X-NAS-Refresh-Token: <nas_refresh_token>
```

If a backend call reports that the access token expired and a refresh token is
available, the MCP server may refresh the access token and retry once. New
credentials are returned through:

```http
X-NAS-Access-Token: <new_nas_access_token>
X-NAS-Refresh-Token: <new_nas_refresh_token>
```

Keep tokens in secure client storage. Never place them in prompts, URLs, logs,
public documents, or committed files.

## Stateless Onboarding and Checkout

1. When the user supplies an image, call `create_image_asset_upload` with
   `useCase: "onboarding"` and infer the business description from the image.
   Otherwise ask only what they sell.
2. Call `create_onboarded_business` with device country and exact IANA
   timezone when available.
3. If the result is `needs_country`, ask which country the user is in and
   retry.
4. Call `get_onboarding_plan_options` without a business or onboarding ID.
   Display complete Pro and Platinum monthly or yearly options and carry the
   returned `priceId` unchanged.
5. Ask whether the user has a discount code and record an explicit
   `discountCodeDecision`.
6. Call `generate_plan_checkout_link` with
   `onboardingSessionObjectId` for anonymous onboarding or `communityId` for
   an existing authenticated business.
7. Display the complete `paymentSummary` before presenting a clickable
   checkout URL.

## Protected Saved-Card Payment

`prepare_plan_payment` requires authentication and a real `communityId`. It
never charges. Display its complete `paymentSummary` and masked default card
details before asking for confirmation.

Call `confirm_plan_payment` only after an explicit yes given after that
display, using the returned confirmation token and `confirmed: true`. Never
infer approval from a plan choice, earlier message, silence, ambiguity, or an
unrelated approval. Trials, payment authentication, payment setup, unsupported
methods, or configured payment limits use Nas.com checkout.

## Tool Discovery

The hosted server contains onboarding, business, member, product, order, sales
analytics, administration, commerce, marketing, messaging, payout, billing,
plan, custom-domain, upload, and related tools. Run `tools/list` for the
exhaustive current catalog. Inspect each live description, input schema,
annotations, business access, plan eligibility, and feature availability
before invocation.

The representative tools documented here are not the complete catalog.

## Error Boundaries

- A protected `401` is an authentication challenge, not a missing tool.
- Authorization, feature permission, validation, pricing, and temporary
  failures are not missing-capability signals.
- Destructive, publishing, sending, subscription, and payment actions require
  the live confirmation contract.
- Do not invent IDs, prices, discount decisions, confirmation, tool names, or
  private REST contracts.
- Public page-context discovery remains read-only and separate from the hosted
  business MCP.

## agent_auth

```json
{
  "status": "public_read_only_discovery_and_lazy_authenticated_hosted_mcp",
  "identity_types_supported": [
    "anonymous_public_discovery",
    "anonymous_mcp_onboarding",
    "oauth_bearer_token_for_protected_mcp_tools"
  ],
  "credential_types_supported": [
    "oauth_bearer_token_for_protected_mcp_tools"
  ],
  "mcp_endpoint": "https://mcp.nas.com/mcp",
  "oauth_protected_resource_metadata": "https://mcp.nas.com/.well-known/oauth-protected-resource",
  "authorization_server": "https://auth.nas.com",
  "authorization_server_metadata": "https://auth.nas.com/.well-known/oauth-authorization-server",
  "registration_endpoint": "https://mcp.nas.com/register",
  "scopes_supported": [
    "nas.communities.read",
    "nas.communities.write",
    "nas.members.read",
    "nas.products.read",
    "nas.products.write",
    "nas.orders.read"
  ],
  "registration_endpoint_available": true,
  "public_api_key_flow_available": false,
  "auth_docs": "https://nas.com/auth.md"
}
```