Mercury Authentication: API Access & Security Guide (2026)

Authentication overview

Mercury provides authentication mechanisms to secure access to its API, allowing developers to programmatically manage banking operations, retrieve account data, and initiate transactions for their businesses Mercury API documentation. The authentication process is designed to ensure that only authorized applications and users can interact with financial data, adhering to industry security standards.

Two primary methods facilitate authentication with the Mercury API: API Keys and OAuth 2.0. The choice between these methods depends on the integration's nature. API Keys are generally suitable for server-to-server integrations where an application accesses its own Mercury account, while OAuth 2.0 is designed for third-party applications that need to access a user's Mercury account on their behalf, without directly handling their credentials OAuth 2.0 specification.

All API interactions with Mercury must occur over HTTPS, ensuring that data transmitted between the client and the Mercury servers is encrypted and protected from eavesdropping and tampering. Mercury's infrastructure is designed with security in mind, including SOC 2 Type II compliance, to protect sensitive financial information Mercury compliance details.

Supported authentication methods

Mercury supports two main authentication methods for its API, each serving different integration requirements and security models.

API Keys

API Keys are long-lived tokens that grant direct access to your Mercury account's resources. They are typically generated from the Mercury dashboard and should be treated as sensitive credentials, similar to passwords. When using API keys, your application includes the key in the request headers to authenticate with the Mercury API. This method is straightforward for applications that operate on behalf of a single Mercury account.

OAuth 2.0

OAuth 2.0 is an authorization framework that allows a third-party application to obtain limited access to a user's Mercury account without exposing the user's login credentials. Instead, the application obtains an access token after the user grants explicit permission. This token can then be used to make API requests on the user's behalf. OAuth 2.0 is the recommended method for public-facing applications or services that integrate with multiple Mercury user accounts, as it provides a more secure and granular way to manage permissions RFC 6749: The OAuth 2.0 Authorization Framework.

Getting your credentials

The process for obtaining authentication credentials for Mercury varies slightly depending on whether you are using API Keys or OAuth 2.0.

For API Keys

1. Log In to Mercury Dashboard: Access your Mercury business account through the official website Mercury login page.
2. Navigate to Developer Settings: Look for a section like "API" or "Developer Settings" within your account dashboard. The exact path may vary, but it is typically found under settings or a dedicated developer portal.
3. Generate New API Key: Within the API section, you should find an option to generate a new API key. You may be prompted to name the key for identification purposes and select specific permissions or scopes that the key will have.
4. Securely Store the Key: Once generated, the API key will be displayed. It is crucial to copy this key immediately and store it securely. Mercury typically shows the key only once, and it cannot be retrieved again if lost.

For OAuth 2.0

Implementing OAuth 2.0 involves registering your application with Mercury to obtain client credentials.

1. Register Your Application: Navigate to the developer section of the Mercury dashboard and register your application. This process typically requires providing details such as your application's name, description, and redirect URIs.
2. Obtain Client ID and Client Secret: Upon successful registration, Mercury will issue a Client ID and Client Secret. These credentials identify your application to Mercury's OAuth server. The Client Secret, like an API key, must be kept confidential.
3. Configure Redirect URIs: Ensure that the redirect URIs configured in your application registration precisely match the URIs where Mercury will send the authorization code after a user grants permission.
4. Implement OAuth Flow: Your application will then need to implement the standard OAuth 2.0 authorization code flow, which involves directing users to Mercury's authorization endpoint, handling the callback, and exchanging the authorization code for an access token and refresh token Mercury API authentication guide.

Authenticated request example

Below is an example of an authenticated API request using an API Key. This example demonstrates how to fetch account details using curl, including the API key in the Authorization header.

curl -X GET \
  'https://api.mercury.com/api/v1/accounts' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer YOUR_MERCURY_API_KEY'

In this example:

• YOUR_MERCURY_API_KEY should be replaced with the actual API key you obtained from your Mercury dashboard.
• The Authorization: Bearer header is a common pattern for sending API keys or access tokens.
• The accept: application/json header indicates that the client expects a JSON response.

For OAuth 2.0, the process is similar, but the Bearer token in the Authorization header would be the access token obtained through the OAuth flow, which typically has a shorter lifespan and is associated with a specific user's permissions.

Security best practices

Securing your integration with Mercury's API is paramount to protect sensitive financial data. Adhering to these best practices helps mitigate common security risks:

API Key Management

• Never hardcode API keys: Do not embed API keys directly into your source code. Use environment variables, configuration files, or secure secret management services.
• Restrict IP addresses: If Mercury supports it, configure your API keys to only accept requests from a specific set of trusted IP addresses. This limits the impact if a key is compromised.
• Use least privilege: Generate API keys with the minimum necessary permissions required for your application's functionality. Avoid granting broad access unless absolutely necessary.
• Rotate keys regularly: Periodically generate new API keys and revoke old ones. This practice reduces the window of exposure for a compromised key.
• Monitor API key usage: Regularly review API logs for unusual activity or excessive requests that might indicate a compromised key.

OAuth 2.0 Best Practices

• Secure Redirect URIs: Ensure your redirect URIs are strictly validated and use HTTPS. Avoid using localhost or generic URLs in production.
• Protect Client Secret: Treat your OAuth Client Secret with the same care as an API key. It should never be exposed in client-side code.
• Use PKCE for Public Clients: For public clients (e.g., mobile apps, single-page applications), implement the Proof Key for Code Exchange (PKCE) extension to OAuth 2.0 to prevent authorization code interception attacks RFC 7636: Proof Key for Code Exchange by OAuth Public Clients.
• Validate State Parameter: Always use and validate the state parameter in OAuth authorization requests to prevent Cross-Site Request Forgery (CSRF) attacks.
• Refresh Token Security: Store refresh tokens securely and use them only when necessary to obtain new access tokens. Implement refresh token rotation if supported.

General Security Practices

• HTTPS Everywhere: Always enforce HTTPS for all communications with the Mercury API to ensure data encryption in transit.
• Input Validation: Sanitize and validate all input to your application to prevent injection attacks and other vulnerabilities.
• Error Handling: Implement robust error handling that avoids exposing sensitive information in error messages.
• Logging and Monitoring: Maintain comprehensive logs of API interactions and monitor them for suspicious patterns. Set up alerts for failed authentication attempts or unusual access patterns.
• Regular Security Audits: Conduct periodic security audits and penetration testing of your application to identify and address vulnerabilities.