title: Scopes

description: Control what actions your API keys and OAuth tokens can perform.

Scopes

Scopes limit what an API key or OAuth token can do. Follow the principle of least privilege — only request the scopes you need.

Available scopes

Scope	Description	Endpoints
`marketplace:read`	List and search marketplace APIs	`GET /v1/marketplace/*`
`marketplace:write`	Submit and manage your own APIs	`POST /v1/marketplace/`, `PUT /v1/marketplace/`
`subscriptions:read`	View subscriptions	`GET /v1/subscriptions/*`
`subscriptions:write`	Create and cancel subscriptions	`POST /v1/subscriptions`, `DELETE /v1/subscriptions/*`
`usage:read`	View usage reports and analytics	`GET /v1/usage/*`
`webhooks:read`	List webhook endpoints	`GET /v1/webhooks/*`
`webhooks:write`	Create and delete webhook endpoints	`POST /v1/webhooks`, `DELETE /v1/webhooks/*`
`billing:read`	View invoices and billing information	`GET /v1/billing/*`

Requesting scopes

API Keys

When creating an API key in the dashboard, select the required scopes from the permissions panel.

OAuth

Pass scopes as a space-separated list in the scope query parameter:

https://platform.wontopos.com/oauth/authorize
  ?client_id=YOUR_CLIENT_ID
  &scope=marketplace:read subscriptions:write usage:read
  &...

No wildcard scopes

Wildcard scopes (e.g. `marketplace:*`) are not supported. Always specify exact scopes.

Default scopes

If no scopes are specified, the following defaults are applied:

Context	Default scopes
API Key	`marketplace:read`
OAuth token	None — scopes are required

OAuth requires explicit scopes

OAuth authorization requests without a `scope` parameter will be rejected.

Scope errors

When a request requires a scope that the token does not have, the API returns:

{
  "error": {
    "type": "insufficient_scope",
    "message": "This action requires the `subscriptions:write` scope.",
    "required_scope": "subscriptions:write"
  }
}

The HTTP status code is 403 Forbidden.

Checking token scopes

Use the token introspection endpoint to verify which scopes a token has:

GET /v1/auth/introspect

{
  "active": true,
  "scopes": ["marketplace:read", "subscriptions:write"],
  "expires_at": "2026-03-30T12:00:00Z"
}