Authentication and permissions

Chowdeck MCP uses OAuth authorization code flow with PKCE (S256). Customers sign in through Chowdeck and approve access for the connecting application. Tool calls run as that customer and expose only the tools allowed by the connection's granted scopes.

This page is for developers implementing a client. If your MCP client already supports OAuth, use the connection flow in Getting started.

Production URLs below use https://api.chowdeck.com.

Choose sandbox or production

For development, use the sandbox MCP endpoint https://console-api.chowdeck.com/mcp as the OAuth resource, with metadata from:

Protected resource: https://console-api.chowdeck.com/.well-known/oauth-protected-resource/mcp
Authorization server: https://console-api.chowdeck.com/.well-known/oauth-authorization-server

The sandbox login and consent frontend is https://sandbox.chowdeck.studio/store/mcp/connect. Begin the OAuth flow at the authorization endpoint returned by discovery; it redirects the customer to login and consent with the required parameters. Use the sandbox issuer, resource, authorization endpoint, and token endpoint together throughout authorization, code exchange, and refresh.

Get your test key from Settings → Developers in the Chowdeck dashboard to access the order simulation console. This key is for console access; sandbox MCP requests still require customer OAuth bearer tokens. See Sandbox setup for the complete setup and simulation flow.

The discovery example below uses production. For sandbox, use the sandbox URLs above. Tokens and identifiers must stay in the environment that issued them.

Discover the authorization server

Use the protected-resource metadata advertised by the server's WWW-Authenticate challenge. For the production endpoint, the metadata URLs are:

Metadata	URL
Protected resource	https://api.chowdeck.com/.well-known/oauth-protected-resource/mcp
Authorization server	https://api.chowdeck.com/.well-known/oauth-authorization-server

Read the metadata to obtain the supported scopes and authorization and token endpoints. Use the exact MCP resource URL, https://api.chowdeck.com/mcp, as the OAuth resource value. Tokens for another resource or environment are not interchangeable.

Identify your client

Chowdeck supports configured clients and, when advertised in authorization-server metadata, Client ID Metadata Documents (CIMD). A CIMD client uses a publicly reachable HTTPS JSON document URL as its client_id.

For example, an application using https://assistant.example/oauth/client-metadata.json as its client ID could serve:

{
  "client_id": "https://assistant.example/oauth/client-metadata.json",
  "client_name": "Example food assistant",
  "application_type": "web",
  "redirect_uris": ["https://assistant.example/oauth/callback"],
  "grant_types": ["authorization_code", "refresh_token"],
  "response_types": ["code"],
  "token_endpoint_auth_method": "none"
}

The document's client_id must match its URL. Serve it directly as application/json over HTTPS; metadata fetches do not follow redirects. Web callbacks must use HTTPS. Native clients can use supported HTTP loopback callbacks with application_type: "native".

Use the scopes advertised by Chowdeck. Listing permissions in a client metadata document does not grant them. If CIMD is unavailable, use a client already configured with Chowdeck; do not assume a dynamic client registration endpoint exists.

Authorize the customer

Generate a fresh PKCE verifier and its base64url-encoded SHA-256 challenge. Send the customer to the discovered authorization endpoint with:

Parameter	Value
`response_type`	`code`
`client_id`	The configured client ID or supported metadata-document URL.
`redirect_uri`	A callback listed for that client.
`resource`	The exact MCP endpoint URL.
`scope`	A space-separated list of supported permissions needed by your application.
`code_challenge_method`	`S256`
`code_challenge`	The PKCE challenge.
`state`	A fresh value your client validates when the customer returns.

After the customer completes sign-in and consent, exchange the authorization code at the discovered token endpoint. Include grant_type: "authorization_code", client_id, redirect_uri, resource, code, and the original code_verifier. Public clients use token endpoint authentication method none, without a client secret.

Authorization codes expire after five minutes. Access tokens have a one-hour lifetime. Use the returned expires_in when managing token expiry.

Permissions

Scope	Tools it enables
`addresses:read`	`get_saved_addresses`
`addresses:write`	`search_addresses`, `resolve_address`, `save_address`
`catalog:read`	`search_restaurants`, `get_restaurant_menu`, `discover_vouchers`
`cart:write`	`create_cart`, `update_cart`, `get_cart`
`checkout:write`	`get_payment_options`, `get_voucher_balances`, `claim_voucher`, `prepare_checkout`, `confirm_checkout`, `get_checkout_status`
`orders:read`	`get_order_status`, `get_order_timeline`

Checkout availability also depends on server spending policy for the currency. Request only advertised scopes, and inspect tools/list after connecting. Read operations such as listing a cart or voucher balances still require the scope shown above.

Refresh the connection

Exchange the current refresh token at the discovered token endpoint with grant_type: "refresh_token", client_id, resource, and refresh_token. An optional scope can narrow access within the original grant.

Refresh tokens rotate: store the newly returned access and refresh tokens together, and use the new refresh token for the next exchange. The refresh authorization has a maximum lifetime of 30 days from its original issuance. If refresh fails because the grant expired or was revoked, restart the customer authorization flow.

Send the access token in Authorization: Bearer ACCESS_TOKEN on MCP requests. Keep tokens out of prompts, URLs, client-visible logs, and source control.

MCP transport

The endpoint accepts MCP requests over HTTP POST and returns JSON responses. It operates without an MCP session ID. A plain browser visit or legacy SSE GET is not a connection test; use an MCP client that initializes the connection and sends the appropriate protocol messages and headers.

See Troubleshooting for authentication and transport errors.