API Scoping and Permissions

Every mCard API request is automatically scoped to your partner account. You only see resources that belong to you or have been associated with your account by mCards. This page explains how scoping works for each API and how webhook event availability is determined.

How Data Scoping Works

When mCards provisions your partner account, it is linked to specific resources on the platform — businesses, distributor cards, currencies, or payment gateways. Every API call you make is automatically filtered to return only the resources associated with your account.

Key behaviors:

List endpoints return only resources within your scope
Detail endpoints return 404 Not Found for resources outside your scope (the API does not distinguish between "does not exist" and "not in your scope" to avoid information leakage)
Write endpoints validate that the target resource is within your scope before allowing the operation

Scoping by API

Distributor API

Your Distributor API access is scoped to the businesses and distributors associated with your partner account. This determines everything you can see through the API:

Resource	Scoped To
Businesses	Only businesses linked to your partner account
Distributors	Distributors belonging to your associated businesses
Distributor cards	Card programs under your accessible distributors
Cardholders	Cardholders who hold cards from your accessible card programs
Transactions	Transactions on cards from your accessible card programs
Locations & terminals	Locations and terminals where your scoped transactions occurred
Campaigns	Campaigns owned by your accessible distributors

Example: If your account is linked to Business A, then GET /api/distributor/v1/cardholders returns only cardholders who hold cards issued under Business A's card programs — not cardholders from other businesses on the platform.

Card API

Your Card API access is scoped to the distributor cards (card programs) associated with your partner account. You can view cardholder cards, transactions, and payment accounts only for cards issued under those programs.

Resource	Scoped To
Cardholder cards	Cards issued under your associated distributor cards
Transactions	Transaction history for cards within your scope
Payment accounts	Payment accounts linked to cards within your scope

Currency API

Your Currency API access is scoped to the currency providers associated with your partner account. You can only view and manage currencies that belong to your currency providers.

Resource	Scoped To
Currencies	Currencies created by your associated currency providers
Distributor cards	Card programs that have been syndicated (linked) to your currencies
Transactions	Currency transactions for cardholders on syndicated card programs

Example: If you are a currency provider with a loyalty points currency, and that currency has been syndicated to Distributor Card X, then you can view cardholders and transactions for cards issued under Distributor Card X — but only in the context of your currency.

Payment API

Your Payment API access is scoped to the payment gateways associated with your partner account. You can manage your gateways and the payment accounts created through them.

Resource	Scoped To
Payment gateways	Gateways registered to your partner account
Payment accounts	Accounts created through your gateways for specific cardholder cards
Syndicated distributor cards	Card programs linked to your payment gateways

Example: If you operate a payment gateway, you can create payment accounts for cardholders on card programs that have been syndicated to your gateway. You cannot access card programs or cardholders outside of that syndication.

Webhook API

Your webhook access is determined by which APIs your partner account has access to. The event types you can subscribe to depend on your integration type:

Integration Type	Available Event Types
Card distribution partners	`transaction`, `location`, `card_status`, `charge.succeeded`, `charge.failed`, `task.recurring.created`, `task.recurring.paused_on_failure`, `task.recurring.completed`
Currency providers	`transaction`, `location`, `claimed_offer`
Payment gateway providers	`payment`, `payment.hold`, `payment.capture`, `payment.release_hold`, `payment.hold_and_capture`, `payment.get_balance`
Full webhook access	All event types listed above

If your partner account spans multiple integration types, the available event types are the union of all types. For example, a partner with both card distribution and currency provider access can subscribe to transaction, location, and claimed_offer events.

Two separate checks apply when you register a webhook:

Endpoint access — calling the Webhook API endpoints at all requires Webhook API access on your partner account. This is checked first; without it, POST /api/webhook/v1/webhooks returns 403 regardless of which event type you asked for.
Event entitlement — the webhook_event_type in the request must be one your account is entitled to, as listed by GET /api/webhook/v1/supported_event_types.

Being entitled to an event type does not by itself grant access to the Webhook API endpoints, and vice versa. If registration returns 403 without naming an event type, it is the first check; if it names the event type or the library, it is the second.

See Webhook API Concepts for details on each event type.

Multi-API Access

A single partner account can have access to multiple APIs simultaneously. For example, a partner might have:

Currency API access scoped to their currency providers
Webhook API access to receive transaction events for currency earning logic
Card API access to view card-level data for their syndicated card programs

Each API's data is independently scoped to the resources associated with your account for that API. Having access to one API does not automatically grant broader access in another.

Common Scoping Scenarios

"I can see some resources but not others"

This is expected behavior. Your API access is scoped to specific resources on the platform. If you need access to additional businesses, card programs, or other resources, contact your mCards partner manager to update your account associations.

"I'm getting 404 for a resource I know exists"

The API returns 404 Not Found for resources outside your scope — even if the resource exists on the platform. Verify that the resource is associated with your partner account.

"I'm getting 403 Forbidden"

A 403 response means your credentials are valid but your partner account does not have access to that API. Contact your mCards partner manager to review your API access.

Related Guides

API Authentication and Credentials — How to authenticate API requests
Webhook API Concepts — Event types and delivery details
Getting Started — Identify which APIs you need