Connect scopes reference

Audience: platforms on Mooov Connect choosing what to request on the consent screen, and merchants deciding what to approve. This is the canonical list; the consent screen renders these same descriptions.

Scopes appear in two places: on your platform key (what Mooov has authorised your integration to do at all) and on each grant (what one tenant has authorised you to do on their account). On every on-behalf-of call your effective permissions are the intersection of the two sets. Revoking a scope on either side blocks the action immediately, even if the other side still carries it.

Direct merchant API keys carry a scope list too, and the same endpoint requirements below apply; there is just no grant in the picture.

1. The scopes

Scope	Permits	Endpoints that require it
`payments:write`	Create, capture, refund, and void payments; charge saved methods; open subscription checkouts	`POST /v1/payment_intents`, `POST /v1/payment_intents/{id}/capture`, `POST /v1/payment_intents/{id}/refund`, `POST /v1/payment_intents/{id}/void`, `POST /v1/charges/saved`, `POST /v1/subscription_checkouts`
`payments:read`	Read payment history and status	`GET /v1/payment_intents/{id}/timeline`
`refunds:write`	Issue refunds (consent-screen granularity; see note)	None yet. Refunds are gated by `payments:write` today
`payouts:read`	Read payout schedule	None yet. Reserved for the payouts API
`customers:write`	Create and update customer records the platform manages	No standalone endpoint. Customer records are created via `customer_ref` / `setup_future_usage` on payment writes, which require `payments:write`
`customers:read`	Resolve your `customer_ref` to the underlying PSP customer	`GET /v1/customers/by_ref`
`mcp:read`	Read-only account context for AI assistants	None yet. Reserved for the account-scoped MCP tiers (see Connect your AI agent)
`webhooks:configure`	Manage webhook destinations	Reserved, not yet active. No endpoint checks it; webhook destinations are configured during the operator ceremony
`*`	Wildcard: satisfies any scope check	Everything above

A few honest footnotes, so you don't request scopes that do nothing:

refunds:write, payouts:read, customers:write, mcp:read, and webhooks:configure are grantable today but not yet enforced by any endpoint. They exist on the consent screen so a tenant's approval is already on record when the corresponding surface ships; requesting them now means no re-prompt later. Until then, refunds ride on payments:write and customer writes happen implicitly through payment creation.
A scope check failure on an endpoint returns 403. For platform keys, a grant whose intersection with your key's scopes is empty is rejected at the on-behalf-of chokepoint with SCOPE_DENIED before the endpoint is reached.

2. The wildcard

* on a key satisfies every scope check, and * on either side of the key/grant intersection widens to the other side's full set.

You cannot obtain * through the consent flow: the consent screen strips * from the requested set before recording the grant, and a request consisting only of * is refused outright. Granting "full account access" via a one-click OAuth screen is too easy a phishing footgun. Wildcard keys are minted directly by Mooov operators where genuinely needed.

3. Defaults

New merchant keys minted from the portal default to payments:write, payments:read (operator-minted keys also include mcp:read).
The platform credential ceremony defaults to payments:write, payments:read, customers:write, webhooks:configure; tell ops@mooov.money if you need a different set.

4. Requesting scopes in the consent flow

Pass them in the authorize URL's scope parameter, OAuth-style space-separated (+ in a query string is a space):

https://connect.mooov.money/authorize
  ?client_id=<slug>
  &redirect_uri=<callback>
  &state=<csrf>
  &scope=payments:write+payments:read+customers:read

Request only what you use. Asking for more scopes than an existing grant carries always requires fresh consent from the tenant; a repeat authorize for the same-or-fewer scopes can complete without re-prompting. The flow itself is walked through in the platform quickstart and §3 of the Connect protocol.