API Reference
update Changelog

Widget Setup

The Araucaria Connect widget is an embeddable UI component that handles bank selection and credential entry securely.

1. Backend: Get Widget Token

First, your backend creates a connection by calling the Araucaria API. This returns a widgetToken that you'll pass to your frontend. The widget token is short-lived (15 minutes) and safe to expose to the browser.

javascript
// Your backend endpoint (e.g., /api/create-connection)
const response = await fetch('https://api.araucaria.money/v1/connections', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer arau_your_api_key',  // Keep this secret on your server
    'Content-Type': 'application/json'
  }
});

const { connectionId, widgetToken } = await response.json();
// Return widgetToken and connectionId to your frontend
⚠️ Important
Never expose your API key (arau_xxx) in frontend code. Always make this call from your backend server.

2. Frontend: Open the Widget

Add the Araucaria script to your HTML, then call Araucaria.open() with the widget token from your backend. This opens a secure modal where users select their bank and enter credentials.

html
<script src="https://api.araucaria.money/widget/araucaria-connect.js"></script>

<script>
// Get widgetToken and connectionId from your backend
Araucaria.open({
  token: widgetToken,
  connectionId: connectionId,

  onSuccess: (metadata) => {
    console.log('Connected!', metadata.connectionId);
    // Connection successful - your backend will receive a webhook
  },

  onExit: (error) => {
    if (error) {
      console.error('Error:', error.message);
    } else {
      console.log('User closed widget');
    }
  }
});
</script>

Callbacks

  • onSuccess(metadata) - Called when connection is established. Receives { connectionId }
  • onExit(error) - Called when user closes the widget or an error occurs

Re-credential Flow

When a previously connected account fails authentication (e.g., user changed their bank password), you can re-open the widget to let the user enter new credentials.

Step 1: When you receive a connection.failed_auth webhook, request a new widget token:

javascript
// Your backend — request a new widget token for re-credentialing
const response = await fetch(
  `https://api.araucaria.money/v1/connections/${connectionId}/widget-token`,
  {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer arau_your_api_key',
      'Content-Type': 'application/json'
    }
  }
);

const { widgetToken, institutionId } = await response.json();
// Pass widgetToken and connectionId to your frontend

Step 2: Open the widget with the new token. The widget will automatically skip institution selection and go directly to the credential form.

javascript
Araucaria.open({
  token: widgetToken,
  connectionId: connectionId,
  onSuccess: (metadata) => {
    console.log('Re-connected!', metadata.connectionId);
    // Connection is CONNECTED again
  },
  onExit: (error) => {
    // User closed without re-credentialing
  }
});
⚠️ Note
The POST /widget-token endpoint only works for connections in FAILED_AUTH status. It returns 409 Conflict for any other state.