Moov Authentication: API Keys, OAuth 2.0 & Security Best Practices

Authentication overview

Moov's API utilizes robust authentication mechanisms to ensure secure access to its payment infrastructure. Developers interacting with the Moov API must authenticate their requests to perform operations such as creating accounts, initiating transfers, or managing wallets. The choice of authentication method depends on the integration's architecture and security requirements, with server-side applications typically using API keys and client-side or multi-party applications leveraging OAuth 2.0. Adhering to secure authentication practices is fundamental for protecting sensitive financial data and maintaining compliance with industry standards like PCI DSS Level 1 and SOC 2 Type II, which Moov itself maintains in its infrastructure.

Authentication is the initial step in securing any interaction with the Moov platform. It verifies the identity of the entity making the request, whether it's your application or an end-user granting permission. Without proper authentication, all API requests are rejected, preventing unauthorized access to financial operations and data. Moov's approach to authentication is designed to be flexible while prioritizing security, offering different methods to suit various integration patterns.

Supported authentication methods

Moov supports two primary authentication methods for accessing its API:

1. API Keys: This method is suitable for server-to-server communication where your backend application directly interacts with the Moov API. API keys are long-lived credentials that grant access to your Moov account and its associated resources.
2. OAuth 2.0: This protocol is designed for delegated authorization, allowing third-party applications to obtain limited access to an end-user's Moov account without exposing their credentials. OAuth 2.0 is particularly useful for marketplaces, platforms, or applications where end-users connect their Moov accounts.

The following table outlines when to use each method and its general security level:

API Keys

Moov API keys consist of a public key and a secret key. The public key identifies your application, while the secret key is used to sign requests, proving their authenticity. API keys should be treated with the same level of security as a password. They grant broad access to your Moov account, so their compromise can lead to significant security breaches. For this reason, Moov recommends creating separate API keys for different environments (e.g., development, staging, production) and services to limit the blast radius if a key is compromised.

OAuth 2.0

OAuth 2.0 is an authorization framework that allows an application to obtain limited access to a user's protected resources on an HTTP service, in this case, Moov. It works by having the user grant permission directly to Moov, which then issues an access token to your application. This token can then be used to make API calls on behalf of the user, within the permissions (scopes) granted. Moov's OAuth 2.0 implementation follows standard flows, typically the authorization code grant flow, which is recommended for web applications to securely obtain tokens. For detailed implementation steps, refer to the Moov API reference documentation.

Getting your credentials

To obtain your Moov API credentials, you need to sign up for a Moov account. Once your account is set up, you can generate API keys directly from your Moov Dashboard. For OAuth 2.0, you will register your application within the dashboard, which will provide you with a client ID and client secret, necessary for initiating the OAuth flow.

API Key Generation

1. Log in to your Moov Dashboard.
2. Navigate to the "API Keys" or "Developers" section.
3. Click on "Create new API Key" or a similar option.
4. You will be presented with your public and secret keys. The secret key is typically shown only once upon creation; make sure to store it securely immediately.

Moov's documentation provides a step-by-step guide on generating and managing API keys.

OAuth 2.0 Client Setup

1. Log in to your Moov Dashboard.
2. Go to the "Applications" or "OAuth Clients" section.
3. Register a new application, providing details such as your application's name, description, and most importantly, the redirect URIs. These URIs are where Moov will send the authorization code after a user grants permission.
4. Upon registration, you will receive a client ID and client secret for your application. These are essential for initiating the OAuth 2.0 authorization flow.

It is crucial to configure your redirect URIs correctly and securely to prevent authorization code interception attacks, as detailed in the OAuth 2.0 security best practices for redirect URIs.

Authenticated request example

When making API requests to Moov, you typically include your API key in the Authorization header using a Bearer token scheme. For OAuth 2.0, the access token is used similarly. Here's an example using curl for an API key:

curl -X GET \
  https://api.moov.io/v1/accounts \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <YOUR_SECRET_API_KEY>'

Replace <YOUR_SECRET_API_KEY> with your actual Moov secret API key. For OAuth 2.0, you would replace it with the access token obtained through the OAuth flow. Moov's SDKs for Node.js, Python, Go, and Ruby abstract much of this complexity, allowing developers to configure their credentials and make authenticated calls more easily.

For instance, using the Node.js SDK:

const moov = require('@moov/node-sdk')('<YOUR_SECRET_API_KEY>');

moov.accounts.list()
  .then(accounts => console.log(accounts))
  .catch(err => console.error(err));

This snippet demonstrates how the SDK simplifies authentication by handling the header construction internally once the API key is provided during initialization.

Security best practices

Securing your Moov integration goes beyond simply using the correct authentication method. Implementing robust security practices is essential to protect your credentials and your users' financial data.

• Never hardcode API keys or client secrets: Store credentials in environment variables, secure configuration files, or a secrets management service (e.g., AWS Secrets Manager, Google Secret Manager, Azure Key Vault). Hardcoding credentials into your source code makes them vulnerable to exposure if your repository is compromised.
• Use environment-specific keys: Create separate API keys for your development, staging, and production environments. This limits the impact if a key from a non-production environment is inadvertently exposed.
• Restrict API key permissions: Where possible, use API keys with the minimum necessary permissions (least privilege principle). While Moov API keys generally provide broad access, always configure any available role-based access controls within your Moov account to limit the operations a key can perform.
• Rotate credentials regularly: Periodically rotate your API keys and OAuth client secrets. This practice minimizes the window of opportunity for an attacker if a credential is compromised without your knowledge.
• Protect redirect URIs for OAuth: Ensure your OAuth redirect URIs are strictly managed and registered only to secure, controlled endpoints. Use https for all redirect URIs.
• Secure your server environment: Implement strong security measures on the servers hosting your application, including firewalls, intrusion detection systems, and regular security updates.
• Monitor API key usage: Regularly review API logs for unusual activity or unauthorized access attempts. Moov's dashboard typically provides logging and monitoring capabilities to help track API usage.
• Implement strong access controls for your Moov Dashboard: Use multi-factor authentication (MFA) for all Moov Dashboard users and ensure that access is granted only to necessary personnel.
• Validate webhooks: If you use Moov webhooks, ensure you validate their signatures to confirm they originate from Moov and have not been tampered with. This prevents spoofing and ensures data integrity. More information on securing webhooks can be found in the Twilio webhook security guide.

By following these best practices, developers can significantly enhance the security posture of their Moov integrations, protecting both their own systems and the sensitive financial data they handle.