API key best practices

API keys are long-lived credentials that authenticate your integration with Airwallex. A compromised key can authorize API calls as if they came from you—including moving funds, changing configuration, or extracting account data—so treating keys as secrets is essential to protecting your account.

This page explains how to limit what a key can do, where it can be used from, how to store and transmit it safely, and when to rotate it. For step-by-step instructions to create and manage keys, see Manage API keys.

Use scoped API keys

A scoped API key grants only the resource permissions you assign (Read or Write on specific APIs), instead of full account access. If a scoped key is compromised, an attacker is limited to those permissions. That is the principle of least privilege applied to API credentials.

For production integrations, create a separate scoped key for each service or use case (for example, one key for payments acceptance and another for reporting) so a single compromise does not unlock unrelated capabilities. See API key scopes for the full scope catalog, and Manage API keys to create scoped keys.

Admin API keys have unrestricted permissions on all Airwallex APIs for the organization or account. Because you can't limit their permissions, we don't recommend using admin keys for new integrations. If you still use an admin API key, migrate that usage to scoped keys.

Restrict where keys can be used

An API key alone is not enough protection if it can be used from anywhere on the internet. IP whitelisting restricts each key so that only requests from declared IPv4 addresses or CIDR ranges succeed. Requests from other addresses receive a 403 response.

IP whitelisting is one of the most effective controls against unauthorized use of a stolen key: even if an attacker obtains the secret, they cannot call Airwallex APIs unless they can also originate traffic from an allowed address. Platform customers with stable egress IPs (for example, through a NAT gateway) should enable whitelisting on every production key.

Store and transmit keys securely

Treat your API key the same way you treat a password or private key.

• Never put keys in source code, repositories, or URLs: Public repositories are continuously scanned for leaked credentials. Private repositories and CI logs can also expose secrets through configuration errors or compromised developer machines. Do not pass API keys as query parameters.
• Pass credentials in request headers: Authenticate with x-client-id and x-api-key when obtaining an access token API. Use the short-lived bearer token for subsequent API calls; do not send the API key on every request if you already hold a valid token.
• Store secrets in a secrets manager or vault: Prefer your cloud or platform secrets store (for example, AWS Secrets Manager, Google Cloud Secret Manager, Azure Key Vault, or HashiCorp Vault) so the key value never appears in application config checked into version control. If a vault is unavailable, use environment variables injected at runtime—not hard-coded values.
• Limit who can view or create keys: Restrict Developer app access in the Airwallex web app to roles that need it (Owner, Admin, or Developer). Share keys only through your organization's secret-management tooling—not email, chat, tickets, or screenshots.
• Assume exposure means compromise: If a key appears in a commit, log, ticket, or message, regenerate it and update every system that used the old value. Do not wait for confirmed abuse.

Rotate keys regularly

Rotation limits how long a leaked key remains usable and confirms that your team can replace credentials under pressure.

Rotate a key when:

• You suspect it was exposed or misused.
• A person or system with access to the key leaves your organization or no longer needs it.
• You complete a security review or scheduled credential rotation.

For scoped API keys, you can duplicate an existing key with the same scopes, deploy the new secret, then delete the old key—reducing downtime during rotation.

Be mindful that regenerating or deleting a key that is still in active use will break callers until they are updated.

Reduce impact beyond the key

API key hygiene works best alongside other account controls:

• Transfer approvals: Route sensitive payouts through an approval workflow so a compromised key alone cannot silently drain funds. See Manage approvals for transfers.
• Sandbox versus production credentials: Use sandbox keys for non-production environments. Never use production keys for local development or shared demos.
• Monitoring: Review security audit logs and webhook notifications for unexpected API key create, regenerate, edit, or delete events.

Key takeaways

• Use scoped API keys and grant only the permissions each integration needs. Migrate off admin keys where you still use them.
• Enable IP whitelisting on production keys whenever you have stable egress IPs.
• Keep keys out of code, repositories, and URLs; store them in a secrets manager and send them only via headers.
• Rotate keys on a schedule and immediately after any suspected exposure.
• Combine key controls with transfer approvals and sandbox discipline to further limit blast radius.

See also

• How-to guides:
  • Manage API keys
  • IP whitelisting
• Reference:
  • API key scopes
  • Security audit logs