Moz Authentication

generated: '2026-08-26'
method: searched
source: https://moz.com/api/docs/guides/authentication
docs: https://moz.com/api/docs/guides/authentication
summary: >-
  Moz runs two distinct authentication models. The JSON-RPC data API uses a static secret API token
  in a custom x-moz-token header. The two beta MCP endpoints use OAuth 2.1 (authorization code +
  PKCE, with dynamic client registration) and also accept the same Moz API token as an HTTP Bearer.
  There is no OpenID Connect surface: /.well-known/openid-configuration 404s on both hosts.
schemes:
- id: moz-api-token
  type: apiKey
  in: header
  name: x-moz-token
  applies_to:
  - https://api.moz.com/jsonrpc
  description: >-
    A secret Moz API token issued from the Moz API dashboard. Sent on every POST to the universal
    JSON-RPC endpoint. Not to be confused with the JSON-RPC "id" field, which is a client-generated
    request identifier and must be at least 24 characters long.
  issuance:
    dashboard: https://moz.com/api/dashboard
    max_active_tokens: 5
    rotation: >-
      Tokens can be deleted after creation; deleting a token immediately breaks any code still using
      it. Moz documents no automatic expiry or rotation schedule.
    signup_requirement: >-
      A separate API subscription is required (distinct from Moz Pro). The free tier requires a
      valid, non-expired credit card, which is not charged unless the account is upgraded.
- id: moz-mcp-oauth
  type: oauth2
  flow: authorization_code
  applies_to:
  - https://api.moz.com/mcp/v1/data
  - https://api.moz.com/mcp/v1/local
  description: >-
    Recommended path for MCP clients. The client walks the user through OAuth sign-in; Moz publishes
    RFC 8414 authorization-server metadata and RFC 9728 protected-resource metadata per endpoint.
  authorization_server: https://api.moz.com
  authorization_endpoint: https://api.moz.com/oauth/authorize
  token_endpoint: https://api.moz.com/oauth/token
  registration_endpoint: https://api.moz.com/oauth/register
  response_types_supported: [code]
  grant_types_supported: [authorization_code]
  code_challenge_methods_supported: [S256]
  token_endpoint_auth_methods_supported: [none]
  scopes_supported: [mcp]
  metadata_documents:
  - well-known/moz-api-oauth-authorization-server.json
  - well-known/moz-api-oauth-protected-resource-mcp-data.json
  - well-known/moz-api-oauth-protected-resource-mcp-local.json
- id: moz-mcp-bearer
  type: http
  scheme: bearer
  applies_to:
  - https://api.moz.com/mcp/v1/data
  - https://api.moz.com/mcp/v1/local
  description: >-
    Manual alternative for clients without OAuth support. The bearer value is the same Moz API key
    used for x-moz-token on the JSON-RPC API; the one token works against both MCP endpoints.
  header: 'Authorization: Bearer <YOUR_MOZ_TOKEN>'
  bearer_methods_supported: [header]
mutual_tls: false
openid_connect: false
observations:
- >-
  The MCP endpoints return a spec-correct 401 with a WWW-Authenticate Bearer challenge carrying a
  resource_metadata parameter, which is the RFC 9728 behaviour MCP clients need for automatic OAuth
  discovery. Probed 2026-08-26.
- >-
  token_endpoint_auth_methods_supported is ["none"], i.e. public clients with PKCE; combined with an
  open registration_endpoint this is the standard MCP client-onboarding shape.
- >-
  The JSON-RPC API has no OAuth path and no scopes; authorization is entirely plan-based (which
  methods a token can call is decided by the subscription tier, not by a scope grant).