Mono Getting Started: Account, Keys, and First API Call (2026)

Getting started overview

Integrating with Mono involves a series of steps designed to enable secure and compliant access to financial data. The initial setup focuses on account creation, key management, and making a foundational API call to establish connectivity. Mono provides a developer dashboard for managing applications, monitoring API usage, and handling user connections. The primary method for initiating data access is through the Mono Connect widget, which facilitates user authentication and authorization with their financial institutions. Alternatively, direct API calls can be made for specific functionalities after a connection is established.

The process generally follows these stages:

1. Account Creation: Register for a Mono developer account.
2. API Key Retrieval: Obtain your unique Secret Key and Public Key from the dashboard.
3. Widget Integration (Recommended): Implement the Mono Connect widget on your client-side application to allow users to link their bank accounts securely.
4. Data Exchange: Use the Secret Key on your server-side to exchange the authorization code received from the widget for an Account ID, which is then used to fetch financial data.
5. Direct API Calls: Make subsequent API requests to access specific data endpoints, such as account balances, transactions, or statements.

Mono supports multiple programming languages through official SDKs, including Node.js SDK installation and Python SDK setup, to streamline integration efforts.

Create an account and get keys

To begin, navigate to the Mono signup page. You will be prompted to provide basic information to create your developer account. After successful registration, you will gain access to the Mono Dashboard.

Accessing API Keys

Upon logging into your dashboard, locate the "Settings" or "Developers" section. Here, you will find your API keys. Mono utilizes two primary types of keys:

• Public Key: Used on the client-side, primarily for initializing the Mono Connect widget. This key is safe to expose in client-side code.
• Secret Key: Used on the server-side for authenticating API requests that retrieve sensitive data. This key must be kept confidential and never exposed in client-side code or public repositories.

You can generate new keys or revoke existing ones from this section as needed for security best practices. For detailed instructions on managing keys, refer to the Mono API keys documentation.

Your first request

The recommended first request involves using the Mono Connect widget to establish a user's bank connection, then exchanging the authorization code for an Account ID on your server. This process ensures secure handling of sensitive credentials.

Step 1: Implement the Mono Connect Widget (Client-Side)

The Mono Connect widget is a pre-built UI component that handles the secure authentication flow between your users and their financial institutions. To integrate it, include the Mono Connect script in your HTML and initialize it with your Public Key.

Example: HTML Integration

<script src="https://connect.mono.co/connect.js"></script>
<button id="connectButton">Connect your bank</button>

<script>
  document.getElementById('connectButton').addEventListener('click', function() {
    MonoConnect.setup({
      key: 'YOUR_PUBLIC_KEY', // Replace with your actual Public Key
      onSuccess: function(data) {
        // Send the 'code' to your server for exchange
        console.log('Connect success:', data.code);
        fetch('/exchange-token', {
          method: 'POST',
          headers: {
            'Content-Type': 'application/json',
          },
          body: JSON.stringify({ code: data.code }),
        })
        .then(response => response.json())
        .then(serverData => console.log('Server response:', serverData))
        .catch(error => console.error('Error exchanging code:', error));
      },
      onClose: function() {
        console.log('Widget closed');
      },
      onLoad: function() {
        console.log('Widget loaded');
      }
    });
    MonoConnect.open();
  });
</script>

Replace 'YOUR_PUBLIC_KEY' with the actual Public Key obtained from your Mono Dashboard. The onSuccess callback provides an authorization code, which is then sent to your server.

Step 2: Exchange Authorization Code for Account ID (Server-Side)

On your server, you will receive the code from the client-side. Use your Secret Key to exchange this code for an Account ID, which is the unique identifier for the linked financial account. This Account ID is crucial for all subsequent data retrieval requests.

Example: Node.js (using fetch or axios)

const express = require('express');
const app = express();
const bodyParser = require('body-parser');
const fetch = require('node-fetch'); // or require('axios')

app.use(bodyParser.json());

const MONO_SECRET_KEY = 'YOUR_SECRET_KEY'; // Replace with your actual Secret Key

app.post('/exchange-token', async (req, res) => {
  const { code } = req.body;

  if (!code) {
    return res.status(400).json({ error: 'Authorization code is required.' });
  }

  try {
    const response = await fetch('https://api.mono.co/v1/accounts/auth', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'mono-sec-key': MONO_SECRET_KEY,
      },
      body: JSON.stringify({ code }),
    });

    const data = await response.json();

    if (response.ok) {
      console.log('Account ID:', data.id);
      // Store data.id securely for future API calls
      res.json({ message: 'Account linked successfully!', accountId: data.id });
    } else {
      console.error('Error exchanging code:', data);
      res.status(response.status).json({ error: data.message || 'Failed to link account.' });
    }
  } catch (error) {
    console.error('Server error during code exchange:', error);
    res.status(500).json({ error: 'Internal server error.' });
  }
});

const PORT = process.env.PORT || 3000;
app.listen(PORT, () => {
  console.log(`Server running on port ${PORT}`);
});

Replace 'YOUR_SECRET_KEY' with your actual Secret Key. The response will contain the id field, which is the Account ID. This ID should be stored securely and associated with your user for subsequent data retrieval.

Step 3: Fetch Account Information (Server-Side)

Once you have the Account ID, you can make authenticated requests to retrieve specific financial data. For example, to get account details:

Example: Node.js (Fetch Account Details)

// Continuing from the previous server-side example

app.get('/account-details/:accountId', async (req, res) => {
  const { accountId } = req.params;

  try {
    const response = await fetch(`https://api.mono.co/v1/accounts/${accountId}`, {
      method: 'GET',
      headers: {
        'mono-sec-key': MONO_SECRET_KEY,
      },
    });

    const data = await response.json();

    if (response.ok) {
      console.log('Account details:', data);
      res.json(data);
    } else {
      console.error('Error fetching account details:', data);
      res.status(response.status).json({ error: data.message || 'Failed to fetch account details.' });
    }
  } catch (error) {
    console.error('Server error fetching account details:', error);
    res.status(500).json({ error: 'Internal server error.' });
  }
});

This endpoint would allow you to retrieve details for a specific Account ID. Ensure you implement proper authentication and authorization for this endpoint in a production environment.

Common next steps

After successfully making your first API call, consider these next steps to further integrate Mono's capabilities:

• Explore Additional Endpoints: Mono offers various endpoints for transactions, statements, identity, and income. Consult the Mono API reference to understand the full range of available data and functionalities. For instance, you might integrate with the transactions endpoint to retrieve a list of financial transactions for a linked account.
• Implement Webhooks: Set up webhooks to receive real-time notifications about events, such as new transactions, account updates, or connection status changes. This is crucial for building reactive applications and reducing the need for constant polling. For guidance on webhook security, resources like Twilio's webhook security guide offer general best practices that can be applied.
• Error Handling and Retries: Implement robust error handling mechanisms and consider retry strategies for transient API failures. The Mono documentation provides insights into common error codes and recommended responses.
• Manage Connections: Develop functionality to manage user connections, including refreshing stale connections, re-authenticating users, and allowing users to disconnect their accounts.
• Security Best Practices: Review and implement security best practices for handling sensitive financial data, including secure storage of API keys and user data, encryption in transit and at rest, and compliance with relevant data protection regulations like Nigeria Data Protection Regulation (NDPR).
• Testing Environment: Utilize Mono's sandbox environment for development and testing without affecting live user data.
• Monitor Usage: Regularly check your API usage and connection limits via the Mono Dashboard to ensure your application operates within your plan's allowances.

Troubleshooting the first call

Encountering issues during the initial setup is common. Here are some troubleshooting tips for your first Mono API call:

• Incorrect API Keys: Double-check that you are using the correct Public Key for client-side integration and the correct Secret Key for server-side authentication. Ensure there are no leading or trailing spaces.
• Environment Mismatch: Verify that you are making API calls to the correct environment (e.g., production vs. sandbox). The base URL for the production API is https://api.mono.co.
• Network Issues: Ensure your server has outbound access to api.mono.co. Firewall rules or network configurations might block the connection.
• CORS Errors: If you are encountering Cross-Origin Resource Sharing (CORS) errors on the client-side, ensure that your application's domain is correctly whitelisted in your Mono Dashboard settings.
• Missing Headers: For server-side calls, confirm that the mono-sec-key header is correctly set with your Secret Key. The Content-Type: application/json header is also essential for requests with a JSON body.
• Invalid Authorization Code: The authorization code received from the Mono Connect widget is short-lived. If you delay sending it to your server for exchange, it might expire, resulting in an error.
• Server-Side Logging: Implement comprehensive logging on your server to capture request and response details for debugging. This can help identify issues with the API call itself or the data being sent/received.
• Consult Documentation: Refer to the Mono error handling documentation for specific error codes and their meanings, which can pinpoint the exact problem.
• Contact Support: If you've exhausted troubleshooting steps, reach out to Mono's support team with relevant request IDs, error messages, and API call details.