# MikroTik Integration Guide

## Video walkthrough

You can watch the setup in the video first. Below the video you will find the same setup written out step by step, with screenshots.

<iframe allowfullscreen="allowfullscreen" height="450" src="https://www.youtube.com/embed/30AHssM7mZ0" style="width: 805px; height: 450px;" width="805"></iframe>

## What is it for?

This guide shows how to connect a MikroTik router to Useroam and set up guest Wi-Fi login (hotspot), the Useroam login connection (RADIUS) and 5651 legal logging. The setup has two parts:

1. **Connecting the device to the panel:** you paste a single line into the device terminal. It only makes the minimum change needed for the panel to connect securely; your existing configuration is not touched.
2. **Setting up the guest network:** the panel reads your device, asks which port should carry the guest network and generates a setup code made for your device. After you read and approve it, you apply it with one more line.

> **Do not want to expose your router to the internet?** In the automatic setup described here, the panel connects to your router over the internet. If you want the router to stay closed from outside, or the panel cannot reach it, follow [Setting up MikroTik without exposing it to the internet (offline)](/books/installation-guides/page/setting-up-mikrotik-without-exposing-it-to-the-internet-offline) instead. On the offline path the panel asks you two questions (the names of the guest interface and the internet uplink), prepares the setup script and gives you a single line to paste into the terminal. When adding a new device, just choose **Offline** as the **Setup method**, or press **Device closed to the internet? Offline setup** under **Device Settings** &gt; **Setup**.

## When do you use it?

- You are connecting a new MikroTik device to Useroam for the first time.
- You set a device up the old way (uploading hotspot files by hand) and want to move it to the new setup.
- You reset or replaced the device and need to connect it again.

## Before you start

- **The address the device uses to reach the internet must match the Device Address saved in the panel.** The setup code only accepts requests from that address. This is the most common problem. If your device sits behind another modem, the panel must hold the modem's public address.
- **The panel must be able to reach your device from outside.** If the device faces the internet directly nothing else is needed (port 443). If it sits behind another modem or firewall, add a port forward there: an external port (e.g. *8443*) must go to port *443* of the MikroTik. You will enter the external port in the **Access port** field. If that is not possible (for example a carrier shared IP, CGNAT), use the [offline setup](/books/installation-guides/page/setting-up-mikrotik-without-exposing-it-to-the-internet-offline).
- **RouterOS 7.1 or newer** is required. RouterOS 6 has no REST API, so the panel cannot manage it.
- **On RouterOS 7.23.3 and above** you must first enable advanced device mode and unplug and replug the device (step 3). You can check your version in the terminal with `/system resource print`.
- You need administrator access to the device with **Winbox** or **SSH** (to open a terminal).
- The device must be added in the panel. If it is not, start at step 1.

## Step by step

1. **Add the device to the panel.** On the **Device Selection** screen press **New Device**. Choose **MikroTik** as **Device Type**. In the **Setup method** that appears below it, keep **Automatic** selected (the path of this guide). Leave **SSL Port** at *443* if the device faces the internet directly, or enter the forwarded external port if it sits behind a modem. Enter the device's public IPv4 address in **Device Address** (e.g. *203.0.113.10*) and the name you want to see in the panel in **Device Name** (e.g. *Kafe-Merkez*), switch on **5651 Loglama** and press **Save**. All fields of this form are on the [Adding a New Device](/books/settings/page/adding-a-new-device) page.
    
    ![New Device form with MikroTik selected, SSL Port, Device Address, Device Name and Save](https://help.useroam.com/uploads/images/gallery/2026-09/mt-yeni-cihaz-en.png)
2. **Generate the setup code.** Open **Device Settings** and switch to the **Setup** tab. The **Step 1: Connect the device to the panel** card reads *No setup code has been generated yet.* Check the **Access port** field (it starts with the SSL Port from step 1) and press **Generate setup code**.
    
    ![Step 1 card with the Access port field and the Generate setup code button](https://help.useroam.com/uploads/images/gallery/2026-09/mt-kart-bos-en.png)
3. **(RouterOS 7.23.3 and above only) Enable device mode.** The yellow box at the top of the card reads *RouterOS 7.23.3 and above: enable advanced device mode first*. Press **Copy**, paste the command into the device terminal and press Enter. Then **unplug the device and plug it back in**; MikroTik will not apply this change without physical confirmation. Skip this step on older versions.
    
    ```
    /system device-mode update mode=advanced
    ```
    
    ![Device mode warning and Copy button](https://help.useroam.com/uploads/images/gallery/2026-09/mt-devmode-en.png)
4. **Copy the single line.** Once the code is generated the card reads *Code is ready, waiting for the device to connect.* and shows the command below three short instructions. Press **Copy**. Under the command, **Code valid until** shows the time the code expires; it is valid for 30 minutes and can be used once.
    
    ![Code ready status, command box and Copy button](https://help.useroam.com/uploads/images/gallery/2026-09/mt-kart-kod-en.png)
5. **Paste the line into the device terminal.** Connect to the device with Winbox or SSH, open a **New Terminal**, paste the line exactly as it is and press Enter. Lines starting with *Useroam: starting...* scroll by; at the end, inside a frame, you should see *USEROAM: connected. The panel can reach this router. Setup complete.*
    
    ![Sample terminal output of the connection setup](https://help.useroam.com/uploads/images/gallery/2026-09/mt-terminal-en.png)
    
    *The image is a sample terminal output; the lines are the setup file's own messages. Depending on your version, RouterOS may print lines of its own as well.*
6. **Refresh the panel.** Reload the **Device Settings** page. The card should read *Connected.* with a **Step 2: Guest network setup** box below it. Press **Open the setup screen**.
    
    ![Connected status and the Open the setup screen button](https://help.useroam.com/uploads/images/gallery/2026-09/mt-kart-hazir-en.png)
7. **Choose the guest network.** The **Setup** section of the MikroTik Management console opens. The **Current State of the Device** card shows what is present and what is missing. In the **Setup Wizard** card, pick the guest port or bridge from **Which interface will carry the guest network** and check **Guest gateway address** and **Portal domain name**.
    
    ![Setup Wizard card with interface, gateway and portal domain name](https://help.useroam.com/uploads/images/gallery/2026-09/mk-kur-secim-en.png)
8. **Choose the security steps and press Next.** The boxes under **Security and compliance steps** are ticked by default; 5651 logging is mandatory and cannot be unticked. We recommend leaving them all ticked. Press **Next**.
    
    ![Security and compliance step boxes and the Next button](https://help.useroam.com/uploads/images/gallery/2026-09/mk-kur-ops-en.png)
9. **Read and approve the script.** The full setup script that will run on the device is shown. Read it, tick *I have read the script and approve running it on this device.* and press **I approve, show the code**.
    
    ![Script review: approval box and I approve, show the code button](https://help.useroam.com/uploads/images/gallery/2026-09/mk-kur-onay-en.png)
10. **Paste the setup line into the device.** The **Single line to paste into the device terminal** appears. Press **Copy**, paste it into the terminal as in step 5 and press Enter. The script first backs up your current settings (*useroam-oncesi-...rsc*), then sets up the guest network.
    
    ![Setup Code card with the command and the Copy button](https://help.useroam.com/uploads/images/gallery/2026-09/mk-kur-kod-en.png)
    
    ![Sample terminal output of the guest network setup](https://help.useroam.com/uploads/images/gallery/2026-09/mt-terminal-kurulum-en.png)
    
    *The image is a sample terminal output; the lines are the script's own messages (some are in Turkish without special characters).*
11. **Check the result.** Open the **Useroam Connection** section in the console. At the top it should read *The Useroam connection appears to be in place*. Then connect a phone to the guest network and open any web page: the Useroam welcome page should appear. The guest who logs in shows up in the **Guests Online Now** list of the **Guest Wi-Fi** section.
    
    ![The Useroam connection appears to be in place, with the RADIUS server](https://help.useroam.com/uploads/images/gallery/2026-09/mk-rad-kurulu-en.png)

## Card statuses

<table id="bkmrk-what-the-card-sayswh"><thead><tr><th>What the card says</th><th>What it means</th><th>What to do</th></tr></thead><tbody><tr><td>*No setup code has been generated yet.*</td><td>No code has been generated for this device.</td><td>Press **Generate setup code**.</td></tr><tr><td>*Code is ready, waiting for the device to connect.*</td><td>A code exists but the device has not fetched it yet.</td><td>Paste the line into the device terminal. If the time has passed, press **Generate a new code**.</td></tr><tr><td>*The device downloaded the setup file, waiting for its confirmation.*</td><td>The device downloaded the file but its "ready" message did not arrive.</td><td>Check the end of the terminal output (error table below). Wait a moment and reload the page.</td></tr><tr><td>*Connected.*</td><td>The panel can reach the device.</td><td>Press **Open the setup screen** in the Step 2 box.</td></tr><tr><td>*The device connected from a different address. Correct the device address in the panel and generate a new code.* with **Last error**: *ip\_mismatch:...* below</td><td>The device reaches the internet from an address other than the one in the panel. The address in the last error is the device's real outgoing address.</td><td>Change the Device Address in **Device Settings** to that address, save, then press **Generate a new code**.</td></tr></tbody></table>

![The device downloaded the setup file, waiting for its confirmation](https://help.useroam.com/uploads/images/gallery/2026-09/mt-kart-indirildi-en.png)

![The device connected from a different address warning with the last error](https://help.useroam.com/uploads/images/gallery/2026-09/mt-kart-ip-en.png)

## Card fields and buttons

<table id="bkmrk-field-%2F-buttonwhat-i"><thead><tr><th>Field / button</th><th>What it does</th><th>Example</th></tr></thead><tbody><tr><td>**Access port**</td><td>The port the panel uses to reach the device. 443 for a device facing the internet directly; behind a modem, the external port you forwarded (the forward must target the MikroTik on port 443).</td><td>443 or 8443</td></tr><tr><td>**Generate setup code** / **Generate a new code**</td><td>Generates a new single-use code valid for 30 minutes. A new code invalidates the old one; only one code is valid at a time.</td><td></td></tr><tr><td>**Copy**</td><td>Copies the command line to the clipboard.</td><td></td></tr><tr><td>**Cancel the code**</td><td>Invalidates an unused code. Use it if you shared the code with the wrong person.</td><td></td></tr><tr><td>**Setup Document**</td><td>Opens the MikroTik help (on the English panel it leads to the MikroTik Management book).</td><td></td></tr><tr><td>**MikroTik Management**</td><td>Opens the MikroTik console once the device is connected.</td><td></td></tr><tr><td>**Legacy setup method (archive)**</td><td>The old way for devices set up by uploading hotspot files by hand. Do not use it for new setups.</td><td></td></tr></tbody></table>

## What does the single line do on the device?

The line from step 4 (connection setup) only does the following on the device; it does not touch your guest network, bridges, DHCP or existing firewall rules:

1. Version check: stops on RouterOS 6.
2. Creates a certificate for HTTPS management (if missing).
3. Adds a user named *useroam-api* that can only log in from the Useroam panel address (*104.247.174.120*).
4. Enables the device's web service (www-ssl, REST API). If you already have your own certificate, it is kept.
5. Adds a single firewall accept rule for the panel address only (*useroam-api-allow*).
6. If a Useroam RADIUS entry already exists, turns off its Message-Authenticator requirement.
7. Sends a "ready" message to the panel; the panel immediately tries to connect back.

To remove this connection, run these three lines in the terminal:

```
/user remove [find name="useroam-api"]
/user group remove [find name="useroam-api"]
/ip firewall filter remove [find comment="useroam-api-allow"]
```

## Error messages you may see in the terminal

<table id="bkmrk-terminal-messagemean"><thead><tr><th>Terminal message</th><th>Meaning</th><th>What to do</th></tr></thead><tbody><tr><td>*Setup code is invalid or malformed.*</td><td>The code was copied incompletely or damaged.</td><td>Copy the line again with **Copy**.</td></tr><tr><td>*Setup code is invalid or has already been used.*</td><td>The code was not recognised or was already used.</td><td>Press **Generate a new code**.</td></tr><tr><td>*Setup code was cancelled in the panel. Generate a new one.*</td><td>The code was cancelled in the panel or replaced by a newer code.</td><td>Use the latest code from the panel.</td></tr><tr><td>*Setup code has expired. Generate a new one in the Useroam panel.*</td><td>The code expired (connection code 30, setup code 60 minutes).</td><td>Generate a new code.</td></tr><tr><td>*This device reached us from ... but the panel has ... Fix the device IP in the panel, then retry.*</td><td>The device's outgoing address does not match the Device Address in the panel.</td><td>Correct the Device Address to the first address, then generate a new code.</td></tr><tr><td>*This device is already connected to Useroam.*</td><td>The device is already connected.</td><td>Nothing to do; go on with **Open the setup screen**.</td></tr><tr><td>*Setup code was already used. Generate a new one in the panel.*</td><td>The same code was run twice.</td><td>Generate a new code.</td></tr><tr><td>*USEROAM ERROR: RouterOS 6 detected ...*</td><td>The device runs RouterOS 6.</td><td>Upgrade to RouterOS 7.1 or newer.</td></tr><tr><td>*USEROAM ERROR: certificate signing timed out.*</td><td>The device could not create the certificate within 90 seconds.</td><td>Run the line again (a new code may be needed).</td></tr><tr><td>*USEROAM: device registered, but the panel could NOT connect back.* and *TCP 443 from 104.247.174.120 must reach THIS router.*</td><td>The device registered but the panel cannot reach it. Usually the device is behind a modem.</td><td>Forward an external port on the modem to port 443 of the MikroTik, enter the external port in **Access port** and generate a new code.</td></tr><tr><td>*USEROAM WARNING: could not reach the Useroam panel.*</td><td>The device could not reach the panel (no internet or DNS).</td><td>Check the device's internet and DNS settings, then run the line again.</td></tr><tr><td>*Useroam panel could not read the generated credentials. Generate a new code.* / *Useroam panel database is unavailable, try again later.*</td><td>A temporary problem on the panel side.</td><td>Generate a new code after a few minutes; contact support if it continues.</td></tr></tbody></table>

## Frequently asked questions

**I pasted the code but the card still says "Code is ready".**  
Look at the terminal output. There is usually a message saying the device cannot reach the panel or that the address does not match (table above). If there is no message, reload the page.

**My device is behind a modem. What should I do?**  
Forward an external port on the modem (e.g. 8443) to port 443 of the MikroTik. In the panel enter 8443 in **Access port** and press **Generate a new code**. The Device Address in the panel must be the modem's public address.

**Will the single line break my existing settings?**  
No. The connection line only adds a certificate, the *useroam-api* user, the web service and one accept rule. The second line, which sets up the guest network, does change settings; this is why the panel first shows you the whole script and why the script takes a backup first. Details are on the [Setup Wizard](/books/mikrotik-management/page/setup-wizard) page.

**I run RouterOS 7.23.3 and the hotspot is not set up.**  
Device mode was not enabled, or the device was not unplugged and replugged after the command. Do step 3.

**I shared the code with someone. Is that a problem?**  
The code only works for requests from the device address saved in the panel and can be used once. If you are unsure, press **Cancel the code**.

## Related pages

- [Adding a New Device](/books/settings/page/adding-a-new-device)
- [Device Settings](/books/settings/page/device-settings)
- [MikroTik Setup Wizard](/books/mikrotik-management/page/setup-wizard)
- [MikroTik Management](/books/mikrotik-management/page/mikrotik-management)
- [Guest Wi-Fi and Useroam Connection](/books/mikrotik-management/page/guest-wi-fi-and-useroam-connection)
What the card says	What it means	What to do
No setup code has been generated yet.	No code has been generated for this device.	Press Generate setup code.
Code is ready, waiting for the device to connect.	A code exists but the device has not fetched it yet.	Paste the line into the device terminal. If the time has passed, press Generate a new code.
The device downloaded the setup file, waiting for its confirmation.	The device downloaded the file but its "ready" message did not arrive.	Check the end of the terminal output (error table below). Wait a moment and reload the page.
Connected.	The panel can reach the device.	Press Open the setup screen in the Step 2 box.
The device connected from a different address. Correct the device address in the panel and generate a new code. with Last error: ip\_mismatch:... below	The device reaches the internet from an address other than the one in the panel. The address in the last error is the device's real outgoing address.	Change the Device Address in Device Settings to that address, save, then press Generate a new code.
Field / button	What it does	Example
Access port	The port the panel uses to reach the device. 443 for a device facing the internet directly; behind a modem, the external port you forwarded (the forward must target the MikroTik on port 443).	443 or 8443
Generate setup code / Generate a new code	Generates a new single-use code valid for 30 minutes. A new code invalidates the old one; only one code is valid at a time.
Copy	Copies the command line to the clipboard.
Cancel the code	Invalidates an unused code. Use it if you shared the code with the wrong person.
Setup Document	Opens the MikroTik help (on the English panel it leads to the MikroTik Management book).
MikroTik Management	Opens the MikroTik console once the device is connected.
Legacy setup method (archive)	The old way for devices set up by uploading hotspot files by hand. Do not use it for new setups.
Terminal message	Meaning	What to do
Setup code is invalid or malformed.	The code was copied incompletely or damaged.	Copy the line again with Copy.
Setup code is invalid or has already been used.	The code was not recognised or was already used.	Press Generate a new code.
Setup code was cancelled in the panel. Generate a new one.	The code was cancelled in the panel or replaced by a newer code.	Use the latest code from the panel.
Setup code has expired. Generate a new one in the Useroam panel.	The code expired (connection code 30, setup code 60 minutes).	Generate a new code.
This device reached us from ... but the panel has ... Fix the device IP in the panel, then retry.	The device's outgoing address does not match the Device Address in the panel.	Correct the Device Address to the first address, then generate a new code.
This device is already connected to Useroam.	The device is already connected.	Nothing to do; go on with Open the setup screen.
Setup code was already used. Generate a new one in the panel.	The same code was run twice.	Generate a new code.
USEROAM ERROR: RouterOS 6 detected ...	The device runs RouterOS 6.	Upgrade to RouterOS 7.1 or newer.
USEROAM ERROR: certificate signing timed out.	The device could not create the certificate within 90 seconds.	Run the line again (a new code may be needed).
USEROAM: device registered, but the panel could NOT connect back. and TCP 443 from 104.247.174.120 must reach THIS router.	The device registered but the panel cannot reach it. Usually the device is behind a modem.	Forward an external port on the modem to port 443 of the MikroTik, enter the external port in Access port and generate a new code.
USEROAM WARNING: could not reach the Useroam panel.	The device could not reach the panel (no internet or DNS).	Check the device's internet and DNS settings, then run the line again.
Useroam panel could not read the generated credentials. Generate a new code. / Useroam panel database is unavailable, try again later.	A temporary problem on the panel side.	Generate a new code after a few minutes; contact support if it continues.