API key scopes

Copy for LLMView as Markdown

A scoped API key is an API credential for your Airwallex account that grants Read or Write access to the resource areas you select, instead of full account access. Each scope controls which REST endpoints the key can call and which webhook events you can subscribe to when using that key, so you can give each integration only the access it needs.

Scoped API keys are recommended for production integrations because they limit blast radius if a credential is exposed. For guidance on least privilege, migrating off admin keys, IP whitelisting, and key storage, see API key best practices.

The tables below list every scope available when you create or edit a key. Use them to plan integrations, document access for your team, or look up what a scope enables when you configure keys in the Airwallex web app.

Scopes reference

Scopes are grouped by product. For each scope, the table shows its label, authorized REST operations for Read and Write access, and webhook events. A dash means no APIs or events apply for that column.

Account Capabilities

Resource	Read	Write	Webhook events
Account Capabilities	Get funding limitsAPI Get capability by IDAPI	Get funding limitsAPI Get capability by IDAPI Enable a capabilityAPI	account_capability.disabled account_capability.enabled account_capability.pending seller.active seller.in_review seller.inactive seller.pending_deactivation seller.rejected seller.suspended

Billing

Resource	Read	Write	Webhook events
Billing Checkouts	Retrieve a Billing CheckoutAPI Get list of Billing CheckoutsAPI	Create a Billing CheckoutAPI Retrieve a Billing CheckoutAPI Get list of Billing CheckoutsAPI Update a Billing CheckoutAPI Cancel a Billing CheckoutAPI	billing_checkout.cancelled billing_checkout.completed billing_checkout.created
Billing Customers	Retrieve a Billing CustomerAPI Get list of Billing CustomersAPI	Create a Billing CustomerAPI Retrieve a Billing CustomerAPI Update a Billing CustomerAPI Get list of Billing CustomersAPI	-
Billing Transactions	Retrieve a Billing TransactionAPI Get list of Billing TransactionsAPI	-	billing_transaction.cancelled billing_transaction.created billing_transaction.succeeded
Credit Notes	Retrieve a Credit NoteAPI Get list of Credit NotesAPI Retrieve a Credit Note Line ItemAPI Get list of Credit Note Line ItemsAPI	Create a Credit NoteAPI Retrieve a Credit NoteAPI Get list of Credit NotesAPI Update a Credit NoteAPI Finalize a Credit NoteAPI Delete a Credit NoteAPI Void a Credit NoteAPI Create Credit Note Line Items and add them to a Credit NoteAPI Retrieve a Credit Note Line ItemAPI Get list of Credit Note Line ItemsAPI Update Credit Note Line Items in a Credit NoteAPI Delete Credit Note Line Items from a Credit NoteAPI	credit_note.created credit_note.finalized credit_note.voided
Discounts	Retrieve a CouponAPI Get list of CouponsAPI	Create a CouponAPI Update a CouponAPI Retrieve a CouponAPI Get list of CouponsAPI	-
Invoices	Retrieve an InvoiceAPI Get list of InvoicesAPI Retrieve an Invoice Line ItemAPI Get list of Invoice Line ItemsAPI	Create an InvoiceAPI Preview an InvoiceAPI Update an InvoiceAPI Delete a draft InvoiceAPI Retrieve an InvoiceAPI Get list of InvoicesAPI Finalize an InvoiceAPI Mark an Invoice as paidAPI Void an InvoiceAPI Create Invoice Line Items and add them to an InvoiceAPI Retrieve an Invoice Line ItemAPI Get list of Invoice Line ItemsAPI Update Invoice Line Items in an InvoiceAPI Delete Invoice Line Items within an InvoiceAPI	invoice.created invoice.finalized invoice.paid invoice.payment.paid invoice.payment_attempt_failed invoice.payment_failed invoice.sent invoice.voided
Payment Sources	Retrieve a Payment SourceAPI Get List of Payment SourcesAPI	Create a Payment SourceAPI Retrieve a Payment SourceAPI Get List of Payment SourcesAPI	-
Prices	Retrieve a PriceAPI Get list of PricesAPI	Create a PriceAPI Retrieve a PriceAPI Update a PriceAPI Get list of PricesAPI	-
Products	Retrieve a ProductAPI Get list of ProductsAPI	Create a ProductAPI Retrieve a ProductAPI Update a ProductAPI Get list of ProductsAPI	-
Subscriptions	Retrieve a SubscriptionAPI Get list of SubscriptionsAPI Retrieve a Subscription ItemAPI Get list of Subscription ItemsAPI	Create a SubscriptionAPI Retrieve a SubscriptionAPI Update a SubscriptionAPI Cancel a SubscriptionAPI Get list of SubscriptionsAPI Retrieve a Subscription ItemAPI Get list of Subscription ItemsAPI	subscription.active subscription.cancelled subscription.created subscription.in_trial subscription.modified subscription.unpaid subscription.updated
Usage Metering	Retrieve a MeterAPI Get list of MetersAPI Get summaries of a MeterAPI	Create a MeterAPI Retrieve a MeterAPI Update a MeterAPI Archive a MeterAPI Restore a MeterAPI Get list of MetersAPI Get summaries of a MeterAPI Ingest a Usage EventAPI Batch Ingest Usage EventsAPI Void a Usage EventAPI	usage_event.aggregation_failed (requires Write scope)

Core Resources

Resource	Read	Write	Webhook events
Balances	Get current balancesAPI Get balance historyAPI	-	-
Deposits	Get a list of depositsAPI Get a deposit by IDAPI	Get a list of depositsAPI Create a deposit via Direct DebitAPI Get a deposit by IDAPI	-
Direct Debits	Get list of direct debitsAPI Get direct debit by IDAPI	Get list of direct debitsAPI Get direct debit by IDAPI Cancel a direct debit by IDAPI	direct_debit.created direct_debit.in_review direct_debit.pending direct_debit.rejected direct_debit.returned direct_debit.settled
Global Accounts	Get current balancesAPI Get balance historyAPI Get a list of global accountsAPI Get a List of Direct Debit Payout MandatesAPI Get a Direct Debit Payout Mandate by IDAPI Get global account by IDAPI Get global account transactionsAPI	Get current balancesAPI Get balance historyAPI Get a list of global accountsAPI Create a global accountAPI Get a List of Direct Debit Payout MandatesAPI Get a Direct Debit Payout Mandate by IDAPI Cancel a Direct Debit Payout Mandate by IDAPI Get global account by IDAPI Close a global accountAPI Generate global account statementAPI Get global account transactionsAPI Update existing global accountAPI	global_account.active global_account.closed global_account.failed
Linked Accounts	Get a list of Linked AccountsAPI Get a Linked Account by IDAPI Get a Direct Debit Deposit MandateAPI Check available balancesAPI	Get a list of Linked AccountsAPI Get a Linked Account by IDAPI Generate a Linked Account authenticationAPI Create a Linked AccountAPI Refresh a Linked Account authenticationAPI Complete the authentication refreshAPI Verify Linked Account with micro-depositsAPI Get a Direct Debit Deposit MandateAPI Update a Direct Debit Deposit MandateAPI Check available balancesAPI Suspend a Linked AccountAPI Confirm a Linked Account among candidate accountsAPI	deposit.pending deposit.rejected deposit.reversed deposit.settled linked_account.failed linked_account.processing linked_account.requires_action linked_account.succeeded linked_account.suspended

Finance

Resource	Read	Write	Webhook events
Financial Reports	Get list of financial reportsAPI Get financial report by IDAPI Get contents of a financial reportAPI	Get list of financial reportsAPI Create a financial reportAPI Get financial report by IDAPI Get contents of a financial reportAPI	-
Financial Transactions	Get list of financial transactionsAPI Get a financial transaction by IDAPI	-	-

Issuing

Resource	Read	Write	Webhook events
Authorizations and Transactions	Get authorization statusAPI Get single authorization statusAPI Get card transaction eventsAPI Get single card transaction eventAPI Get card transaction lifecyclesAPI Get single card transaction lifecycleAPI Get card transactionsAPI Get single card transactionAPI Get transactionsAPI Get single transactionAPI	-	-
Cardholders	Get all cardholdersAPI Get cardholder detailsAPI	Create a cardholderAPI Update a cardholderAPI Delete cardholderAPI	issuing.cardholder.deleted issuing.cardholder.disabled issuing.cardholder.incomplete issuing.cardholder.pending issuing.cardholder.ready
Cards	Get sensitive card detailsAPI Get all cardsAPI Get card detailsAPI Get card remaining limitsAPI	Create a cardAPI Activate a cardAPI Update a cardAPI	issuing.card_notification.created issuing.card_notification.physical_activated issuing.card.modified issuing.card.pending issuing.card.failed issuing.card.inactive issuing.card.active issuing.card.lost issuing.card.stolen issuing.card.closed issuing.card.blocked issuing.card.expired issuing.card.low_remaining_transaction_limit
Config	Get issuing configAPI	Update issuing configAPI	-
Digital Wallet Tokens	Get single digital wallet tokenAPI Get all digital wallet tokensAPI	-	issuing.digital_wallet_notification.abandoned_provisioning issuing.digital_wallet_notification.payment_reminder issuing.digital_wallet_notification.token_activated issuing.digital_wallet_notification.token_provisioning_otp issuing.digital_wallet_notification.wallet_available issuing.digital_wallet_token.created issuing.digital_wallet_token.provision_attempted issuing.digital_wallet_token.updated
Merchant Brands	Get single Merchant Brand by idAPI Get all Merchant Brands matching queryAPI	-	-
Transaction Disputes	Get a transaction disputeAPI Get all transaction disputesAPI	Create a transaction disputeAPI Update a transaction disputeAPI Submit a transaction disputeAPI Cancel a transaction disputeAPI	issuing.transaction_dispute.accepted issuing.transaction_dispute.cancelled issuing.transaction_dispute.created issuing.transaction_dispute.expired issuing.transaction_dispute.lost issuing.transaction_dispute.modified issuing.transaction_dispute.rejected issuing.transaction_dispute.submitted issuing.transaction_dispute.won

Payment Acceptance

Resource	Read	Write	Webhook events
Funds Splits	Retrieve a FundsSplitReversalAPI Get list of FundsSplitReversalsAPI Retrieve a FundsSplitAPI Get list of FundsSplitsAPI	Create a FundsSplitReversalAPI Create a FundsSplitAPI Release a FundsSplitAPI	funds_split.created funds_split.failed funds_split.released funds_split.settled
Payment Acceptance	Get list of settlementsAPI Get a settlement by IDAPI Get a settlement report by IDAPI Get Apple Pay DomainsAPI Get convertible shopper currenciesAPI Retrieve a Conversion QuoteAPI Retrieve a CustomerAPI Generate a client secret for a CustomerAPI Get list of CustomersAPI Retrieve a PaymentAttempt by IDAPI Retrieve list of PaymentAttemptsAPI Retrieve a PaymentConsentAPI Get list of PaymentConsentsAPI Retrieve a PaymentIntentAPI Get list of PaymentIntentsAPI Retrieve a PaymentLinkAPI Get list of PaymentLinksAPI Retrieve a PaymentMethodAPI Get list of PaymentMethodsAPI Retrieve BIN InfoAPI Retrieve a RefundAPI Get list of RefundsAPI	Add Apple Pay DomainsAPI Remove Apple Pay DomainsAPI Create a Conversion QuoteAPI Create a CustomerAPI Update a CustomerAPI Create a PaymentConsentAPI Update a PaymentConsentAPI Verify a PaymentConsentAPI Continue to verify a PaymentConsentAPI Disable a PaymentConsentAPI Create a PaymentIntentAPI Update a PaymentIntentAPI Confirm a PaymentIntentAPI Continue to confirm a PaymentIntentAPI Increment Authorization for a PaymentIntentAPI Capture a PaymentIntentAPI Cancel a PaymentIntentAPI Create a PaymentLinkAPI Update a PaymentLinkAPI Send a PaymentLinkAPI Activate a PaymentLinkAPI Deactivate a PaymentLinkAPI Create a RefundAPI	customer.created customer.creation_failed customer.update_failed customer.updated payment_attempt.authentication_failed payment_attempt.authentication_redirected payment_attempt.authorization_voided payment_attempt.authorized payment_attempt.cancelled payment_attempt.capture_failed payment_attempt.capture_requested payment_attempt.captured payment_attempt.expired payment_attempt.failed payment_attempt.failed_to_process payment_attempt.paid payment_attempt.payment_code_generated payment_attempt.payment_code_generation_failed payment_attempt.pending_authorization payment_attempt.received payment_attempt.risk_declined payment_attempt.settled payment_attempt.succeeded payment_consent.created payment_consent.disabled payment_consent.paused payment_consent.pending payment_consent.requires_customer_action payment_consent.requires_payment_method payment_consent.updated payment_consent.verification_failed payment_consent.verified payment_intent.cancelled payment_intent.capture_required payment_intent.created payment_intent.customer_action_required payment_intent.merchant_action_required payment_intent.payment_failed payment_intent.payment_method_required payment_intent.pending payment_intent.requires_capture payment_intent.requires_customer_action payment_intent.requires_payment_method payment_intent.succeeded payment_intent.updated refund.accepted refund.failed refund.processing refund.received refund.settled refund.succeeded
Payment Disputes	Retrieve a PaymentDisputeAPI Get list of PaymentDisputesAPI Get list of Related Payment IntentsAPI	Retrieve a PaymentDisputeAPI Get list of PaymentDisputesAPI Accept a PaymentDisputeAPI Challenge a PaymentDisputeAPI Get list of Related Payment IntentsAPI	dispute.accepted dispute.arbitration_escalate_received_by_merchant dispute.dispute_received_by_merchant dispute.dispute_responded_by_merchant dispute.dispute_reversed dispute.lost dispute.pre_arbitration_received_by_merchant dispute.pre_chargeback_accepted dispute.pre_chargeback_received_by_merchant dispute.rfi_received_by_merchant dispute.rfi_responded_by_merchant dispute.won payment_dispute.accepted payment_dispute.challenged payment_dispute.expired payment_dispute.lost payment_dispute.pending_closure payment_dispute.pending_decision payment_dispute.requires_response payment_dispute.reversed payment_dispute.won payment_method.attached payment_method.attachment_failed payment_method.created payment_method.creation_failed payment_method.detached payment_method.detachment_failed payment_method.disable_failed payment_method.disabled payment_method.updated
Payment Links	Retrieve a PaymentLinkAPI Get list of PaymentLinksAPI	Create a PaymentLinkAPI Update a PaymentLinkAPI Retrieve a PaymentLinkAPI Send a PaymentLinkAPI Activate a PaymentLinkAPI Deactivate a PaymentLinkAPI Get list of PaymentLinksAPI	payment_link.created payment_link.paid
POS Terminals	Retrieve a TerminalAPI Get list of TerminalsAPI	Create a TerminalAPI Process a PaymentIntent in a TerminalAPI Activate a TerminalAPI Deactivate a TerminalAPI Terminate a TerminalAPI Update a TerminalAPI Reset a Terminal passwordAPI	pos.terminal.activated pos.terminal.admin_password_status.activated pos.terminal.admin_password_status.locked pos.terminal.admin_password_status.reset_requested pos.terminal.deactivated pos.terminal.refund_password_status.activated pos.terminal.refund_password_status.locked pos.terminal.refund_password_status.opted_out pos.terminal.refund_password_status.reset_requested pos.terminal.terminated pos.terminal.updated

Payouts

Resource	Read	Write	Webhook events
Beneficiaries	Get list of beneficiariesAPI Get a beneficiary by IDAPI	Get list of beneficiariesAPI Create a new beneficiaryAPI Validate beneficiaryAPI Get a beneficiary by IDAPI Delete existing beneficiaryAPI Update existing beneficiaryAPI Get the API schemaAPI Get the form schemaAPI Get supported financial institutionsAPI	-
Transfers	List all batch transfersAPI Retrieve a batch transferAPI List all items within a batchAPI Get list of transfersAPI Get transfer by IDAPI Supported currenciesAPI	Create confirmation letterAPI List all batch transfersAPI Create a batch transferAPI Retrieve a batch transferAPI Add items to a batchAPI Delete a batch transferAPI Delete items within a batchAPI List all items within a batchAPI Quote a batch transferAPI Submit a batch transferAPI Get list of transfersAPI Create a new transferAPI Validate transferAPI Get transfer by IDAPI Cancel a transferAPI Confirm funding for a transferAPI Supported currenciesAPI	connected_account_transfer.failed connected_account_transfer.new connected_account_transfer.pending connected_account_transfer.settled connected_account_transfer.suspended transfer.failed transfer.new transfer.pending transfer.settled transfer.suspended

Risk

Resource	Read	Write	Webhook events
Request for Information (RFI)	List all RFIsAPI Retrieve an RFIAPI	List all RFIsAPI Retrieve an RFIAPI Respond to an RFIAPI	rfi.action_required rfi.answered rfi.closed

Connected Accounts

Resource	Read	Write	Webhook events
Account	Retrieve account detailsAPI	-	-
Charges	Get list of chargesAPI Get a charge by IDAPI	Create a new chargeAPI	charge.failed charge.new charge.pending charge.settled charge.suspended
Connected Accounts	Get account by IDAPI Get list of connected accountsAPI	Create an accountAPI Update a connected accountAPI Submit account for activationAPI Agree to terms and conditionsAPI Suspend accountAPI Reactivate accountAPI	account.action_required account.active account.connected account.submitted account.suspended
Hosted Flows	Get flowAPI	Create flowAPI Authorize flowAPI	-
Invitation Links	Get an account invitation link by IDAPI	Create an account invitation linkAPI	-
Offboarding	List offboardingsAPI Get an offboarding by IDAPI	List offboardingsAPI Get an offboarding by IDAPI Create an offboardingAPI	-
Platform Reports	Get Platform reportAPI	Create Platform reportAPI	platform_report.completed platform_report.failed
PSP Settlement Deposits	Get a list of PSP settlement depositsAPI	-	psp_settlement_deposit.new psp_settlement_deposit.action_required psp_settlement_deposit.matched psp_settlement_deposit.settled
PSP Settlement Intents	Get a PSP settlement intent by IDAPI Get a list of PSP settlement intentsAPI	Get a PSP settlement intent by IDAPI Get a list of PSP settlement intentsAPI Create a new PSP settlement intentAPI Update a PSP settlement intentAPI Cancel a PSP settlement intent by IDAPI Submit a PSP settlement intent by IDAPI Split a PSP settlement intentAPI	psp_settlement_intent.new psp_settlement_intent.cancelled psp_settlement_intent.submitted psp_settlement_intent.action_required psp_settlement_intent.matched psp_settlement_intent.settled
PSP Settlement Splits	Get a PSP settlement split by IDAPI Get list of PSP settlement splitsAPI	Get a PSP settlement split by IDAPI Get list of PSP settlement splitsAPI Release a PSP settlement split by IDAPI Cancel a PSP settlement split by IDAPI	psp_settlement_split.new psp_settlement_split.create_failed psp_settlement_split.cancelled psp_settlement_split.matched psp_settlement_split.pending psp_settlement_split.failed psp_settlement_split.settled
Transfers	Get list of connected account transfersAPI Get a connected account transfer by IDAPI	Create a new connected account transferAPI	connected_account_transfer.failed connected_account_transfer.new connected_account_transfer.pending connected_account_transfer.settled connected_account_transfer.suspended transfer.failed transfer.new transfer.pending transfer.settled transfer.suspended

Simulations

Resource	Read	Write	Webhook events
Simulations	-	AccountsAPI BillingAPI DepositsAPI IssuingAPI Linked AccountsAPI Payment AcceptanceAPI Request for Information (RFI)API TransfersAPI	-

Spend

Resource	Read	Write	Webhook events
Bills	List billsAPI Get billAPI	Create billAPI Update bill sync statusAPI Mark bill as paidAPI	spend.bill.awaiting_approval spend.bill.updated spend.bill.awaiting_payment spend.bill.payment_in_progress spend.bill.paid spend.bill.rejected spend.bill.scheduled spend.bill.deleted
Expenses	List expensesAPI Get expenseAPI List reimbursement reportsAPI Get reimbursement reportAPI List reimbursementsAPI Get reimbursementAPI Get reimbursement report transferAPI	Update expense sync statusAPI Update reimbursement report transfer sync statusAPI Update reimbursement report sync statusAPI Mark reimbursement report as paidAPI	spend.expense.draft spend.expense.awaiting_approval spend.expense.updated spend.expense.rejected spend.expense.approved spend.expense.archived spend.expense.deleted spend.reimbursement_report.draft spend.reimbursement_report.awaiting_approval spend.reimbursement_report.awaiting_payment spend.reimbursement_report.rejected spend.reimbursement_report.payment_in_progress spend.reimbursement_report.paid spend.reimbursement_report.mark_as_paid spend.reimbursement_report.deleted spend.reimbursement_report.updated
Purchase Orders	List purchase ordersAPI Get purchase orderAPI	Create purchase orderAPI Update purchase order sync statusAPI	-
Vendors	List vendorsAPI Get vendorAPI	Create vendorAPI Update vendor sync statusAPI	-

Supporting Services

Resource	Read	Write	Webhook events
Upload Files	-	Upload a fileAPI	-

Transactional FX

Resource	Read	Write	Webhook events
Conversion	Get current balancesAPI Get balance historyAPI Retrieve a conversionAPI List all conversionsAPI Retrieve an amendmentAPI List all amendmentsAPI Retrieve a quoteAPI Retrieve a current rateAPI	Get current balancesAPI Get balance historyAPI Create a conversionAPI Retrieve a conversionAPI List all conversionsAPI Create an amendment quoteAPI Create an amendmentAPI Retrieve an amendmentAPI List all amendmentsAPI Create a quoteAPI Retrieve a quoteAPI Retrieve a current rateAPI	-

Was this page helpful?