# MRI Software — Accounting API: connection

> Canonical URL: https://developers.apideck.com/apis/accounting/mrisoftware/connection

# How to connect to MRI Software

MRI Software authenticates with **HTTP Basic credentials** tied to a dedicated **Web Services
user** in your own MRI installation. There is no OAuth sign-in screen and nothing to authorize in
MRI: you create the Web Services user in MRI **Security Console**, then enter five values in
Vault.

Set aside time for step 1 and step 2: they need an MRI security administrator, and the connection
cannot be created until they are done.

---

## Prerequisites

- An MRI installation with **Web Services / MIX APIs** licensed. Every connection targets your own
  installation, so you will need its hostname.
- **Security Console** administrator access, including the **Modify Roles** permission, required
  to create or edit Web Services classes.
- The MRI APIs listed in step 1 licensed for your installation.

You do **not** need to whitelist any IP addresses for this connection.

---

## 1. Create a Web Services class with rights to the APIs

A Web Services class is what grants API-level rights. In MRI Security Console:

1. Go to **Classes** and select the **Web Services** tab.
2. Select the **database** you are granting access to. Note the database name: you will need it
   in step 3.
3. Click **Add**.
4. In the **Create Web Service Class** dialog, enter a unique **name** (maximum 20 characters) and
   a **description** (maximum 40 characters), then save.
5. On the Class Management page, select **each function (API)** the class may access, then save.

Full MRI instructions: [Adding Web Services Classes](https://mrix5.saas.mrisoftware.com/SecurityConsole/Help/Web_Services/Adding_Web_Services_Classes.htm).

Grant the class access to the MRI APIs below; these are the exact APIs the connector calls:

| Data you want to sync | MRI API |
|---|---|
| Departments: **also used to validate the connection** | `MRI_S-PMAP_Departments` |
| Ledger accounts | `MRI_S-PMGL_Accounts` |
| Journal entries (read) | `MRI_S-PMGL_JournalEntries` |
| Journal entries (create) | `MRI_S-PMGL_CreateJournalEntryV3` |
| Customers | `MRI_S-PMAP_Clients` |
| Suppliers (read) | `MRI_S-PMAP_VendorsV2` |
| Suppliers (create) | `MRI_S-PMAP_CreateVendors` |
| Bills (read) | `MRI_S-PMAP_InvoiceDataV2` |
| Bills (create) | `MRI_S-PMAP_CreateInvoiceAdvancedV3` |
| Purchase orders | `MRI_S-PMAP_PurchaseOrderDetails` |
| Locations | `MRI_S-PMAM_Locations` |
| Tax rates | `MRI_S-PMCM_RentTaxRates` |
| Subsidiaries (entities) | `MRI_S-PMGL_EntityListing` |

You only need the `Create…` APIs if your integration writes records back to MRI.

> **`MRI_S-PMAP_Departments` is mandatory even if you never read departments.** Apideck validates
> a new connection by calling the departments list API, so the connection stays invalid until that
> one call succeeds, which means the API must be licensed for your installation *and* permitted
> for the Web Services class.

---

## 2. Add a Web Services user and assign the class

1. Create the user through Security Console's normal *Adding and Maintaining Users and Access
   Rights* flow.
2. Select the **Web Services User** option while creating the user.
3. On the **User Security Assignments** tab, assign the Web Services class you created in step 1.
   Only Web Services classes are selectable for this user type, and you can assign more than one.

Full MRI instructions: [Adding Web Services Users and Assigning Web Services Classes](https://mrix5.saas.mrisoftware.com/SecurityConsole/Help/Web_Services/Adding_Web_Services_Users_and_Assigning_Web_Services_Classes.htm).

Two things to expect:

- A Web Services user **cannot log on to MRI applications**. That is by design, not a
  misconfiguration.
- On MRI SaaS installations, Web Services users are visible only to super administrators.

Record the user name and password: they are two of the five values Vault needs.

---

## 3. Gather the five connection values

| Vault field | What to enter |
|---|---|
| **Domain** | The hostname of your MRI installation only: for example `mrix5.saas.mrisoftware.com`. Do **not** include `https://` or any path: Apideck builds the full base URL as `https://{domain}/MRIAPIServices/` for you. |
| **Client ID** | Your MRI client ID. If you are not sure which identifier this is, your MRI administrator or MRI Support can confirm it. |
| **MRI Application Database Name** | The name of the MRI application database, the same database you selected in step 1. |
| **Username** | The Web Services user name from step 2. |
| **Password** | That Web Services user's password. |

### How these values are combined

Apideck assembles the Basic authentication user name for you, in the slash-delimited shape MRI's
API documentation requires:

```
clientID/databaseName/webServicesUsername/partnerKey
```

That string plus your Web Services password is Base64-encoded into an `Authorization: Basic …`
header on every call.

The **partner key is not yours to supply**. It is the MIX Partner Key that the application owner,
the team whose integration you are connecting to, has configured at integration level. If any one
of the four slash-separated segments is wrong, MRI returns a 401 without indicating which one, so
double-check Client ID, database name and user name for typos and stray spaces before saving.

---

## 4. Connect in Vault

1. Open Vault and select **MRI Software**.
2. Enter **Domain**, **Client ID**, **MRI Application Database Name**, **Username** and
   **Password**.
3. Click **Save**.

Apideck immediately validates the connection by calling the departments list API. If the call
succeeds the connection becomes usable; if it fails the connection stays invalid: see
Troubleshooting below.

---

## Notes

- **Credentials are installation-specific.** The base URL embeds your domain and the Basic user
  name embeds your client ID and database name, so a set of credentials only ever works against
  the installation it was issued for. A sandbox or test installation needs its own separate
  connection.
- **Nothing expires on a timer.** Basic credentials have no token lifetime, so the connection keeps
  working indefinitely, but it breaks the moment the Web Services user's password is rotated, the
  user is disabled, or the Web Services class loses access to an API. Update the password in Vault
  whenever it changes.
- **Do not reuse a human login.** A normal MRI client login will not authenticate against the API;
  only a Web Services user with an assigned Web Services class will.

---

## Troubleshooting

### 401 Unauthorized

MRI returns the same 401 for **five distinct causes** and the response does not say which one
applies. Work through them in this order:

| # | Cause | What to check |
|---|---|---|
| 1 | The Basic user name is not in the required `clientID/databaseName/webServicesUsername/partnerKey` shape | Re-check **Client ID**, **MRI Application Database Name** and **Username** in Vault for typos, leading or trailing spaces, or an accidentally pasted `https://`. An empty value collapses a segment and invalidates the whole user name. |
| 2 | The `Authorization` header is not of type `Basic` | Apideck always sends Basic. This only applies if you are also testing MRI directly with your own tooling: make sure you are not sending a Bearer token. |
| 3 | The partner key is not authorized for your MRI client | Ask the application owner to have MRI authorize their MIX Partner Key for your client ID. Authorization is per client. |
| 4 | The partner key is not authorized for the specific API being called | Same route, but per API. Send the exact API name (for example `MRI_S-PMAP_InvoiceDataV2`). Note that a newly authorized API can keep failing for up to 24 hours because partner keys cache the API structure. |
| 5 | The Web Services user has no license or rights for that API | Re-open the Web Services class in Security Console and confirm the API's function is selected, and that the class is still assigned to the user. |

### The connection will not turn valid after saving

Validation calls the departments list API. If the five values look correct, confirm
`MRI_S-PMAP_Departments` is licensed for your installation and selected as a function on the Web
Services class. A connection with otherwise perfect credentials stays invalid until that single
call succeeds.

### Some resources work, others return 401

Rights are granted per API, not per connection. Add the missing API's function to the Web Services
class (step 1) and ask the application owner to confirm the partner key is authorized for it.

### Still stuck

Because a 401 does not identify its own cause, clearing one often needs MRI. Raise it with your MRI
account team or MRI Support, quoting the exact API name and the time of the failed call. For
anything on the Apideck side, contact
[Apideck Support](https://help.apideck.com/en/articles/7774658).

---

## Reference

- [About Web Services](https://mrix5.saas.mrisoftware.com/SecurityConsole/Help/Web_Services/About_Web_Services.htm): MRI Security Console setup overview
- [Adding Web Services Classes](https://mrix5.saas.mrisoftware.com/SecurityConsole/Help/Web_Services/Adding_Web_Services_Classes.htm)
- [Adding Web Services Users and Assigning Web Services Classes](https://mrix5.saas.mrisoftware.com/SecurityConsole/Help/Web_Services/Adding_Web_Services_Users_and_Assigning_Web_Services_Classes.htm)
- [MRI API Integrations Guide](https://www.mrisoftware.com/wp-content/uploads/2018/01/MRI-API-Integrations-Guide-5.pdf) (PDF): Basic authentication and the composite user name


[API reference](https://developers.apideck.com/apis/accounting/reference.md) · [Coverage matrix](https://developers.apideck.com/apis/accounting/coverage)